Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { existsSync, readdirSync, rmSync } from 'node:fs';
import { join, resolve } from 'node:path';
import {
type ClassifiedGitAuthError,
classifyGitAuthError,
credentialHostFromRemoteUrl,
currentCliCommandName,
isBranchNotFoundGitError,
isLoginFixableGitAuthError,
shellSingleQuote,
} from '@inkeep/open-knowledge-core';
import {
assertCheckoutSymlinksSafe,
assertGitAvailable,
type Config,
type CredentialUrlMatchReader,
type GitHubAccountSource,
GitNotAvailableError,
GitProbeTimeoutError,
GitTooOldError,
loginShapedUserinfoUser,
redactShareSubprocessStderr,
resolveGitHubAccountFromUrl,
sameGitHubLogin,
UnsafeIncomingSymlinkError,
} from '@inkeep/open-knowledge-server';
import { Command } from 'commander';
import simpleGit, { GitPluginError, type SimpleGitOptions } from 'simple-git';
import type { GhDetectResult } from '../auth/gh-detect.ts';
import { type ResolvedAuth, resolveAuth } from '../auth/resolve-auth.ts';
import { makeLazyTokenStore, type TokenStore } from '../auth/token-store.ts';
import { OK_DIR } from '../constants.ts';
import { parseGitUrl } from '../github/url.ts';
import { isGitHubRepoPublic } from '../github/visibility.ts';
import { addOkPathsToGitExclude } from '../sharing/git-exclude.ts';
const STAGE_RANGES: [string, number, number][] = [
['count', 0, 10],
['compress', 10, 20],
['receiv', 20, 60],
['resolv', 60, 100],
];
function parseProgressLine(line: string): { stage: string; pct: number } | null {
const m = /^([\w ]+):\s+(\d+)%/.exec(line.trim());
if (!m) return null;
const label = m[1].toLowerCase();
const raw = Number(m[2]);
for (const [key, start, end] of STAGE_RANGES) {
if (label.includes(key)) {
return { stage: m[1], pct: Math.round(start + (raw / 100) * (end - start)) };
}
}
return null;
}
function emit(json: boolean, obj: Record<string, unknown>): void {
if (json) process.stdout.write(`${JSON.stringify(obj)}\n`);
}
export function buildCloneEnv(sourceEnv: NodeJS.ProcessEnv = process.env): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(sourceEnv)) {
if (value !== undefined) env[key] = value;
}
env.GIT_TERMINAL_PROMPT = '0';
env.LANG = 'C';
env.LC_ALL = 'C';
return env;
}
export function buildCloneAuthEnv(
resolved: Pick<ResolvedAuth, 'relayToken'>,
sourceEnv: NodeJS.ProcessEnv = process.env,
): Record<string, string> {
const env = buildCloneEnv(sourceEnv);
if (resolved.relayToken) {
env.OK_GH_TOKEN = resolved.relayToken.token;
env.OK_GH_TOKEN_HOST = resolved.relayToken.host;
if (resolved.relayToken.login) env.OK_GH_TOKEN_LOGIN = resolved.relayToken.login;
else delete env.OK_GH_TOKEN_LOGIN;
} else {
delete env.OK_GH_TOKEN;
delete env.OK_GH_TOKEN_HOST;
delete env.OK_GH_TOKEN_LOGIN;
}
return env;
}
export function resolveSelfCliArgs(
argv: readonly string[] = process.argv,
execPath: string = process.execPath,
): string[] {
const entry = argv[1];
return entry ? [execPath, entry] : [execPath];
}
export function buildCloneArgs(branch: string | null | undefined): string[] {
if (typeof branch !== 'string' || branch.length === 0) return ['--progress'];
return ['--progress', '-b', branch];
}
export const isBranchNotFoundError = isBranchNotFoundGitError;
export async function cloneWithBranchFallback(opts: {
branch: string | null;
clone: (args: string[]) => Promise<unknown>;
onFallback: (branch: string) => void;
}): Promise<{ fellBack: boolean }> {
try {
await opts.clone(buildCloneArgs(opts.branch));
return { fellBack: false };
} catch (err) {
if (opts.branch !== null && isBranchNotFoundError(err)) {
opts.onFallback(opts.branch);
await opts.clone(buildCloneArgs(null));
return { fellBack: true };
}
throw err;
}
}
interface CloneOptions {
json: boolean;
dir?: string;
branch?: string | null;
onAuthResolved?: (info: { tier: ResolvedAuth['tier']; login?: string }) => void;
_detectGhFn?: (host?: string, options?: { login?: string }) => GhDetectResult;
}
export function buildCloneGitOptions(cwd: string, gitConfig: string[]): Partial<SimpleGitOptions> {
return {
baseDir: cwd,
config: gitConfig,
unsafe: {
allowUnsafeCredentialHelper: true,
allowUnsafePager: true,
allowUnsafeSshCommand: true,
allowUnsafeAskPass: true,
allowUnsafeEditor: true,
allowUnsafeConfigEnvCount: true,
},
};
}
export function shouldSkipAuthForPublicRepo(
protocol: string,
hostname: string,
isPublic: boolean,
): boolean {
return protocol === 'https' && hostname === 'github.com' && isPublic;
}
export interface CloneAuthResolution {
auth: ResolvedAuth;
declaredMiss?: {
declaredLogin: string;
declaredSource: Exclude<GitHubAccountSource, 'active'>;
};
}
export function formatDeclaredAccountMiss(
miss: CloneAuthResolution['declaredMiss'],
wording: { url: string; operation: string },
): string | null {
if (miss === undefined) return null;
const { declaredLogin, declaredSource } = miss;
let mechanism: string;
switch (declaredSource) {
case 'remote-url':
mechanism = `${wording.url} names ${declaredLogin}`;
break;
case 'credential-config':
mechanism = `Your Git credential configuration names ${declaredLogin}`;
break;
default:
mechanism = `Your Git configuration names ${declaredLogin}`;
}
return (
`⚠ ${mechanism}, but the GitHub CLI couldn't confirm that account — ${wording.operation} used its active account.\n` +
` Run \`gh auth status\` to see which account that is. If ${declaredLogin} is listed as active, nothing is wrong; confirming an account by name needs GitHub CLI 2.40 or newer.\n`
);
}
export function formatDeclaredMissWarning(
miss: CloneAuthResolution['declaredMiss'],
): string | null {
return formatDeclaredAccountMiss(miss, { url: 'The clone URL', operation: 'the clone' });
}
export async function resolveCloneAuth(
cloneUrl: string,
tokenStore: TokenStore,
options: {
selfCliArgs?: readonly string[];
cwd?: string;
_detectGhFn?: (host?: string, options?: { login?: string }) => GhDetectResult;
_readCredentialUrlMatch?: CredentialUrlMatchReader;
} = {},
): Promise<CloneAuthResolution> {
const parsed = parseGitUrl(cloneUrl);
if (!parsed) {
throw new Error(`Invalid git URL: ${stripUrlPassword(cloneUrl)}`);
}
if (cloneUrl.trim().startsWith('http://')) return { auth: { tier: 'none', gitConfig: [] } };
const account = resolveGitHubAccountFromUrl(cloneUrl, {
cwd: options.cwd,
_readCredentialUrlMatch: options._readCredentialUrlMatch,
});
const credentialHost = credentialHostFromRemoteUrl(cloneUrl) ?? undefined;
const auth = await resolveAuth(
account.host ?? parsed.hostname,
tokenStore,
{ selfCliArgs: options.selfCliArgs, login: account.login, credentialHost },
options._detectGhFn,
);
const declaredMiss =
account.login !== undefined &&
auth.tier === 'A' &&
!sameGitHubLogin(auth.relayToken?.login, account.login)
? { declaredLogin: account.login, declaredSource: account.source }
: undefined;
return { auth, ...(declaredMiss !== undefined ? { declaredMiss } : {}) };
}
export function resolveCloneUrl(
rawUrl: string,
parsed: { hostname: string; owner: string; name: string },
): string {
const ownerRepo = `${parsed.owner}/${parsed.name}`;
const isShorthand = rawUrl === ownerRepo || rawUrl === `${ownerRepo}.git`;
return isShorthand ? `https://${parsed.hostname}/${ownerRepo}` : rawUrl;
}
export async function runClone(
url: string,
opts: CloneOptions,
_config: Config,
cwd = process.cwd(),
): Promise<string> {
const parsed = parseGitUrl(url);
if (!parsed) {
throw new Error(`Invalid git URL: ${stripUrlPassword(url)}`);
}
const cloneUrl = resolveCloneUrl(url, parsed);
const targetDir = opts.dir ? resolve(cwd, opts.dir) : resolve(cwd, parsed.name);
const targetExisted = existsSync(targetDir);
if (targetExisted) {
const entries = readdirSync(targetDir);
if (entries.length > 0) {
throw new Error(`Target directory is not empty: ${targetDir}`);
}
}
assertGitAvailable();
const tokenStore = makeLazyTokenStore();
const shouldProbe = parsed.protocol === 'https' && parsed.hostname === 'github.com';
const isPublic = shouldProbe ? await isGitHubRepoPublic(parsed.owner, parsed.name) : false;
const resolution: CloneAuthResolution = shouldSkipAuthForPublicRepo(
parsed.protocol,
parsed.hostname,
isPublic,
)
? { auth: { tier: 'none', gitConfig: [] } }
: await resolveCloneAuth(cloneUrl, tokenStore, {
selfCliArgs: resolveSelfCliArgs(),
cwd,
...(opts._detectGhFn ? { _detectGhFn: opts._detectGhFn } : {}),
});
const resolved: ResolvedAuth = resolution.auth;
opts.onAuthResolved?.({ tier: resolved.tier, login: resolved.relayToken?.login });
if (!opts.json) {
const declaredMissWarning = formatDeclaredMissWarning(resolution.declaredMiss);
if (declaredMissWarning) process.stderr.write(declaredMissWarning);
}
const env = buildCloneAuthEnv(resolved);
const gitOptions = buildCloneGitOptions(cwd, resolved.gitConfig);
const git = simpleGit(gitOptions).env(env);
let lastPct = -1;
git.outputHandler((_cmd, _stdout, stderr) => {
stderr.on('data', (chunk: Buffer) => {
const text = chunk.toString('utf-8');
for (const line of text.split('\n')) {
const prog = parseProgressLine(line);
if (prog && prog.pct !== lastPct) {
lastPct = prog.pct;
emit(opts.json, { type: 'progress', pct: prog.pct, stage: prog.stage });
if (!opts.json) {
process.stderr.write(`\r Cloning ${prog.pct}%`);
}
}
}
});
});
const requestedBranch =
typeof opts.branch === 'string' && opts.branch.length > 0 ? opts.branch : null;
await cloneWithBranchFallback({
branch: requestedBranch,
clone: (args) => git.clone(cloneUrl, targetDir, [...args, '--no-checkout']),
onFallback: (branch) => {
emit(opts.json, { type: 'branch-fallback', branch });
if (!opts.json) {
process.stderr.write(
`\n Branch '${branch}' not found upstream — cloning default branch instead.\n`,
);
}
},
});
if (!opts.json) process.stderr.write('\n');
const cloned = simpleGit({ ...gitOptions, baseDir: targetDir }).env(env);
if ((await cloned.raw(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'])).trim() !== '') {
try {
await assertCheckoutSymlinksSafe(cloned, 'HEAD', env);
} catch (err) {
rmSync(targetExisted ? join(targetDir, '.git') : targetDir, { recursive: true, force: true });
throw err;
}
await cloned.raw(['checkout', '--force', 'HEAD']);
}
try {
const { runInit } = await import('./init.ts');
const initResult = await runInit({ cwd: targetDir, projectRootMode: 'cwd', mcp: false });
if (initResult.contentUpdated.length > 0) {
const msg = `auto-init: updated ${initResult.contentUpdated.join(', ')}`;
if (opts.json) emit(true, { type: 'warning', message: msg });
else process.stderr.write(` ${msg}\n`);
}
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
if (opts.json) emit(true, { type: 'warning', message: `auto-init: ${msg}` });
else process.stderr.write(` auto-init: ${msg}\n`);
}
try {
ensureOkExcludedFromGit(targetDir);
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
if (opts.json) emit(true, { type: 'warning', message: `git-exclude: ${msg}` });
else process.stderr.write(` git-exclude: ${msg}\n`);
}
return targetDir;
}
export function ensureOkExcludedFromGit(
projectDir: string,
): 'appended' | 'already-present' | 'no-exclude' {
const result = addOkPathsToGitExclude(projectDir, [`${OK_DIR}/`]);
if (result.kind === 'no-exclude') return 'no-exclude';
if (result.kind === 'refused-tracked') return 'already-present';
if (result.appended.length > 0) return 'appended';
return 'already-present';
}
const SHELL_SAFE_TOKEN = /^[A-Za-z0-9._/:@-]+$/;
function stripUrlPassword(url: string): string {
return url.replace(
/^([a-z][a-z0-9+.-]*:\/\/)([^/]*)@/i,
(_whole, scheme: string, userinfo: string) => {
const colon = userinfo.indexOf(':');
const user = colon === -1 ? userinfo : userinfo.slice(0, colon);
return user !== '' && loginShapedUserinfoUser(user) !== undefined
? `${scheme}${user}@`
: scheme;
},
);
}
function quoteIfNeeded(s: string): string {
return SHELL_SAFE_TOKEN.test(s) ? s : shellSingleQuote(s);
}
function reconstructCloneCommand(url: string, branch: string | null | undefined): string {
const branchSuffix =
typeof branch === 'string' && branch.length > 0 ? ` -b ${quoteIfNeeded(branch)}` : '';
return `${currentCliCommandName()} clone ${quoteIfNeeded(url)}${branchSuffix}`;
}
export function formatCloneAuthFailure(opts: {
error: unknown;
url: string;
branch?: string | null;
principal?: string | null;
resolvedLogin?: string | null;
}): string | null {
const classified: ClassifiedGitAuthError = classifyGitAuthError(opts.error);
if (classified.kind !== 'auth') return null;
const displayUrl = stripUrlPassword(opts.url);
if (isLoginFixableGitAuthError(classified)) {
const reRun = reconstructCloneCommand(displayUrl, opts.branch);
return [
`✗ Couldn't clone ${displayUrl} — authentication is required.`,
'',
' To fix:',
` 1. Run: ${currentCliCommandName()} auth login`,
` 2. Then re-run: ${reRun}`,
].join('\n');
}
if (classified.subclass === '403') {
const principalHint =
typeof opts.principal === 'string' && opts.principal.length > 0
? ` (signed in as @${opts.principal} — may lack access)`
: '';
return `✗ Access denied when cloning ${displayUrl}${principalHint}. Check that your account has access to the repository.`;
}
if (classified.subclass === 'ssh-auth') {
return `✗ Couldn't clone ${displayUrl} over SSH — authentication failed. Check that your SSH key is added to your GitHub account and the host key is trusted, or clone the HTTPS URL instead.`;
}
if (classified.subclass === 'not-found-as-identity') {
const identity =
typeof opts.resolvedLogin === 'string' && opts.resolvedLogin.length > 0
? ` Authenticated as ${opts.resolvedLogin}.`
: '';
return `✗ Repository not found when cloning ${displayUrl}. It may not exist, or the account used may not have access.${identity}`;
}
return [
'✗ Your GitHub token is missing required OAuth scopes — likely the `repo` scope.',
'',
' To fix:',
' 1. Create a token with `repo` scope at https://github.com/settings/tokens',
` 2. Run: ${currentCliCommandName()} auth pat`,
` 3. Then re-run: ${reconstructCloneCommand(displayUrl, opts.branch)}`,
].join('\n');
}
function formatCloneEnvConfigRefusal(opts: {
error: unknown;
message: string;
url: string;
branch?: string | null;
}): string | null {
if (!(opts.error instanceof GitPluginError) || opts.error.plugin !== 'unsafe') return null;
if (!opts.message.startsWith('Configuring ')) return null;
const displayUrl = stripUrlPassword(opts.url);
return [
`✗ Couldn't clone ${displayUrl} — a Git setting passed in through the GIT_CONFIG_COUNT and GIT_CONFIG_KEY_<n> environment variables was refused:`,
` ${opts.message}`,
'',
' To fix:',
' 1. Remove that setting from the GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> variables, or unset GIT_CONFIG_COUNT',
` 2. Then re-run: ${reconstructCloneCommand(displayUrl, opts.branch)}`,
].join('\n');
}
export function emitCloneFailure(opts: {
error: unknown;
url: string;
branch?: string | null;
json: boolean;
emit: (event: Record<string, unknown>) => void;
printStderr: (text: string) => void;
principal?: string | null;
resolvedLogin?: string | null;
}): void {
const rawMessage =
opts.error instanceof UnsafeIncomingSymlinkError
? `The repository has symlinks that are unsafe to check out: ${opts.error.describeLinks()}. The clone was removed. Remove or fix these links on the remote, then clone again.`
: redactShareSubprocessStderr(
opts.error instanceof Error ? opts.error.message : String(opts.error),
);
if (opts.json) {
opts.emit(
opts.error instanceof UnsafeIncomingSymlinkError
? {
type: 'error',
code: 'unsafe-symlinks',
message: `The repository has ${opts.error.unsafe.length} symlink(s) that are unsafe to check out. The clone was removed. Remove or fix these links on the remote, then clone again.`,
refusedSymlinkPaths: opts.error.displayPaths(),
}
: { type: 'error', message: rawMessage },
);
return;
}
const actionable =
formatCloneAuthFailure({
error: opts.error,
url: opts.url,
branch: opts.branch,
principal: opts.principal,
resolvedLogin: opts.resolvedLogin,
}) ??
formatCloneEnvConfigRefusal({
error: opts.error,
message: rawMessage,
url: opts.url,
branch: opts.branch,
});
opts.printStderr(`${actionable ?? `✗ ${rawMessage}`}\n`);
}
export async function resolveClonePrincipal(
tokenStore: TokenStore,
host: string,
): Promise<string | null> {
const entry = await tokenStore.get(host);
const login = entry?.login;
return login && login !== 'unknown' ? login : null;
}
export async function handleCloneFailure(opts: {
error: unknown;
url: string;
branch: string | null;
json: boolean;
emit: (event: Record<string, unknown>) => void;
printStderr: (text: string) => void;
resolvePrincipal?: (host: string) => Promise<string | null>;
auth?: { tier: ResolvedAuth['tier']; login?: string };
}): Promise<void> {
const classified = classifyGitAuthError(opts.error);
const ghAuth = opts.auth?.tier === 'A' ? opts.auth : undefined;
let principal: string | null = null;
if (!opts.json && classified.kind === 'auth' && classified.subclass === '403') {
if (ghAuth) {
principal = ghAuth.login ?? null;
} else if (opts.auth?.tier !== 'none') {
const target = parseGitUrl(opts.url);
if (target) {
const resolve =
opts.resolvePrincipal ?? ((host) => resolveClonePrincipal(makeLazyTokenStore(), host));
principal = await resolve(target.hostname);
}
}
}
emitCloneFailure({
error: opts.error,
url: opts.url,
branch: opts.branch,
json: opts.json,
principal,
resolvedLogin: ghAuth?.login ?? null,
emit: opts.emit,
printStderr: opts.printStderr,
});
}
export function cloneCommand(getConfig: () => Config): Command {
return new Command('clone')
.description('Clone a git repository and open it')
.argument('<url>', 'Repository URL or owner/repo shorthand')
.argument('[dir]', 'Target directory (default: ./<repo-name>)')
.option('--json', 'Output JSONL progress events', false)
.option('-b, --branch <branch>', 'Branch to check out (falls back to default if missing)')
.action(
async (url: string, dir: string | undefined, opts: { json: boolean; branch?: string }) => {
const config = getConfig();
let authInfo: { tier: ResolvedAuth['tier']; login?: string } | undefined;
try {
const targetDir = await runClone(
url,
{
json: opts.json,
dir,
branch: opts.branch ?? null,
onAuthResolved: (info) => {
authInfo = info;
},
},
config,
);
if (opts.json) {
emit(true, { type: 'complete', dir: targetDir });
} else {
process.stderr.write(`✓ Cloned to ${targetDir}\n`);
process.chdir(targetDir);
const { startCommand } = await import('./start.ts');
const startCmd = startCommand(getConfig);
await startCmd.parseAsync([], { from: 'user' });
}
} catch (err) {
if (
err instanceof GitNotAvailableError ||
err instanceof GitProbeTimeoutError ||
err instanceof GitTooOldError
) {
if (opts.json) {
emit(true, { type: 'error', message: err.message });
} else {
process.stderr.write(`${err.message}\n`);
}
process.exitCode = 78;
return;
}
await handleCloneFailure({
error: err,
url,
branch: opts.branch ?? null,
json: opts.json,
auth: authInfo,
emit: (event) => emit(true, event),
printStderr: (text) => process.stderr.write(text),
});
process.exitCode = 1;
}
},
);
}