ghcrawl 0.0.1 → 0.1.0

package/bin/ghcrawl.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const binDir = path.dirname(fileURLToPath(import.meta.url));
+const entrypoint = path.join(binDir, '..', 'src', 'main.ts');
+const require = createRequire(import.meta.url);
+const tsxLoader = require.resolve('tsx');
+
+const child = spawn(process.execPath, ['--import', tsxLoader, entrypoint, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+
+child.on('error', (error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,35 +1,50 @@
 {
   "name": "ghcrawl",
-  "version": "0.0.1",
-  "description": "Placeholder package reserving the ghcrawl name. Full release coming soon.",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ghcrawl terminal UI and CLI runtime",
   "author": "PwrDrvr LLC <harold@pwrdrvr.com>",
   "license": "MIT",
-  "type": "module",
-  "homepage": "https://github.com/pwrdrvr/gitcrawl",
+  "homepage": "https://github.com/pwrdrvr/ghcrawl",
   "bugs": {
-    "url": "https://github.com/pwrdrvr/gitcrawl/issues"
+    "url": "https://github.com/pwrdrvr/ghcrawl/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pwrdrvr/gitcrawl.git"
+    "url": "git+https://github.com/pwrdrvr/ghcrawl.git"
   },
   "keywords": [
     "ghcrawl",
     "github",
-    "cli"
+    "cli",
+    "tui",
+    "sqlite",
+    "embeddings"
   ],
-  "bin": {
-    "ghcrawl": "./index.mjs"
+  "engines": {
+    "node": ">=22"
   },
   "files": [
-    "index.mjs",
-    "README.md",
-    "LICENSE"
+    "bin",
+    "src"
   ],
-  "engines": {
-    "node": ">=18"
-  },
   "publishConfig": {
     "access": "public"
+  },
+  "bin": {
+    "ghcrawl": "./bin/ghcrawl.js",
+    "gitcrawl": "./bin/ghcrawl.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@types/blessed": "^0.1.27",
+    "neo-blessed": "^0.2.0",
+    "tsx": "^4.20.5",
+    "@ghcrawl/api-core": "0.1.0"
+  },
+  "scripts": {
+    "cli": "tsx src/main.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test src/*.test.ts src/**/*.test.ts"
   }
-}
+}

package/src/init-wizard.test.ts

@@ -0,0 +1,185 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { readPersistedConfig, writePersistedConfig } from '@ghcrawl/api-core';
+
+import { runInitWizard, type InitPrompter } from './init-wizard.js';
+
+function makeTestEnv(overrides: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    XDG_CONFIG_HOME: undefined,
+    APPDATA: undefined,
+    ...overrides,
+  };
+}
+
+function makePrompter(overrides: Partial<InitPrompter> = {}): InitPrompter {
+  return {
+    intro: async () => undefined,
+    note: async () => undefined,
+    select: async () => 'plaintext',
+    text: async () => {
+      throw new Error('unexpected text prompt');
+    },
+    confirm: async () => true,
+    password: async () => {
+      throw new Error('unexpected password prompt');
+    },
+    outro: async () => undefined,
+    cancel: () => undefined,
+    ...overrides,
+  };
+}
+
+test('runInitWizard skips prompting when config already has both API keys', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ghcrawl-init-test-'));
+  const env = makeTestEnv({ HOME: home });
+  writePersistedConfig(
+    {
+      githubToken: 'ghp_testtoken1234567890',
+      openaiApiKey: 'sk-proj-testkey1234567890',
+    },
+    { env },
+  );
+
+  const result = await runInitWizard({
+    env,
+    prompter: makePrompter(),
+    isInteractive: true,
+  });
+
+  assert.equal(result.changed, false);
+  assert.equal(fs.existsSync(result.configPath), true);
+});
+
+test('runInitWizard prompts for missing keys and writes the config file', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ghcrawl-init-test-'));
+  const env = makeTestEnv({ HOME: home });
+  const prompts: string[] = [];
+
+  const result = await runInitWizard({
+    env,
+    prompter: makePrompter({
+      select: async () => 'plaintext',
+      password: async ({ message }) => {
+        prompts.push(message);
+        return message.includes('GitHub') ? 'ghp_testtoken1234567890' : 'sk-proj-testkey1234567890';
+      },
+    }),
+    isInteractive: true,
+  });
+
+  assert.equal(result.changed, true);
+  assert.deepEqual(prompts, ['GitHub personal access token', 'OpenAI API key']);
+
+  const persisted = readPersistedConfig({ env });
+  assert.equal(persisted.data.githubToken, 'ghp_testtoken1234567890');
+  assert.equal(persisted.data.openaiApiKey, 'sk-proj-testkey1234567890');
+});
+
+test('runInitWizard can persist detected environment keys without prompting for secrets', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ghcrawl-init-test-'));
+  const env = makeTestEnv({
+    HOME: home,
+    GITHUB_TOKEN: 'ghp_envtoken1234567890',
+    OPENAI_API_KEY: 'sk-proj-envkey1234567890',
+  });
+
+  const result = await runInitWizard({
+    env,
+    prompter: makePrompter({
+      select: async () => 'plaintext',
+      confirm: async () => true,
+    }),
+    isInteractive: true,
+  });
+
+  assert.equal(result.changed, true);
+  const persisted = readPersistedConfig({ env });
+  assert.equal(persisted.data.githubToken, 'ghp_envtoken1234567890');
+  assert.equal(persisted.data.openaiApiKey, 'sk-proj-envkey1234567890');
+});
+
+test('runInitWizard can configure 1Password CLI metadata without persisting plaintext keys', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ghcrawl-init-test-'));
+  const env = makeTestEnv({ HOME: home });
+  const notes: Array<{ title?: string; message: string }> = [];
+  const confirms: string[] = [];
+
+  const result = await runInitWizard({
+    env,
+    prompter: makePrompter({
+      select: async () => 'op',
+      text: async ({ message }) => (message.includes('vault') ? 'Private' : 'ghcrawl'),
+      note: async (message, title) => {
+        notes.push({ title, message });
+      },
+      confirm: async ({ message }) => {
+        confirms.push(message);
+        return true;
+      },
+    }),
+    isInteractive: true,
+  });
+
+  assert.equal(result.changed, true);
+  const persisted = readPersistedConfig({ env });
+  assert.equal(persisted.data.secretProvider, 'op');
+  assert.equal(persisted.data.opVaultName, 'Private');
+  assert.equal(persisted.data.opItemName, 'ghcrawl');
+  assert.equal(persisted.data.githubToken, undefined);
+  assert.equal(persisted.data.openaiApiKey, undefined);
+  assert.equal(
+    notes.some((entry) => entry.title === '1Password Setup' && entry.message.includes('op://Private/ghcrawl/GITHUB_TOKEN')),
+    true,
+  );
+  assert.equal(notes.some((entry) => entry.title === 'Next Commands' && entry.message.includes('ghcrawl-op()')), true);
+  assert.equal(notes.some((entry) => entry.title === 'Next Commands' && entry.message.includes('ghcrawl-op doctor')), true);
+  assert.equal(notes.some((entry) => entry.title === 'Next Commands' && entry.message.includes('ghcrawl-op sync org/repo')), true);
+  assert.equal(notes.some((entry) => entry.title === 'Responsibility' && entry.message.includes('accept no liability')), true);
+  assert.equal(confirms.some((message) => message.includes('I created the Secure Note')), true);
+  assert.equal(confirms.some((message) => message.includes('I copied those commands')), true);
+  assert.equal(confirms.some((message) => message.includes('accept full responsibility')), true);
+});
+
+test('runInitWizard accepts empty 1Password vault and item input as defaults', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ghcrawl-init-test-'));
+  const env = makeTestEnv({ HOME: home });
+
+  await runInitWizard({
+    env,
+    prompter: makePrompter({
+      select: async () => 'op',
+      text: async () => '',
+      confirm: async () => true,
+    }),
+    isInteractive: true,
+  });
+
+  const persisted = readPersistedConfig({ env });
+  assert.equal(persisted.data.opVaultName, 'Private');
+  assert.equal(persisted.data.opItemName, 'ghcrawl');
+});
+
+test('runInitWizard accepts undefined 1Password text responses as defaults', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ghcrawl-init-test-'));
+  const env = makeTestEnv({ HOME: home });
+
+  await runInitWizard({
+    env,
+    prompter: makePrompter({
+      select: async () => 'op',
+      text: async () => undefined,
+      confirm: async () => true,
+    }),
+    isInteractive: true,
+  });
+
+  const persisted = readPersistedConfig({ env });
+  assert.equal(persisted.data.opVaultName, 'Private');
+  assert.equal(persisted.data.opItemName, 'ghcrawl');
+});

package/src/init-wizard.ts

@@ -0,0 +1,323 @@
+import { cancel, confirm, intro, isCancel, note, outro, password, select, text } from '@clack/prompts';
+import {
+  loadConfig,
+  readPersistedConfig,
+  writePersistedConfig,
+  isLikelyGitHubToken,
+  isLikelyOpenAiApiKey,
+} from '@ghcrawl/api-core';
+
+type InitSecretMode = 'plaintext' | 'op';
+
+export type InitWizardResult = {
+  configPath: string;
+  changed: boolean;
+};
+
+export type InitPrompter = {
+  intro: (message: string) => Promise<void> | void;
+  note: (message: string, title?: string) => Promise<void> | void;
+  select: (options: {
+    message: string;
+    initialValue?: string;
+    options: Array<{ value: string; label: string; hint?: string }>;
+  }) => Promise<string | symbol>;
+  text: (options: {
+    message: string;
+    placeholder?: string;
+    validate?: (value: string) => string | undefined;
+  }) => Promise<string | symbol | undefined>;
+  confirm: (options: { message: string; initialValue?: boolean }) => Promise<boolean | symbol>;
+  password: (options: { message: string; validate?: (value: string) => string | undefined }) => Promise<string | symbol>;
+  outro: (message: string) => Promise<void> | void;
+  cancel: (message: string) => void;
+};
+
+function resolveTextValue(value: string | symbol | undefined, fallback: string): string | symbol {
+  if (isCancel(value)) {
+    return value;
+  }
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+export function createClackInitPrompter(): InitPrompter {
+  return {
+    intro,
+    note,
+    select,
+    text,
+    confirm,
+    password,
+    outro,
+    cancel,
+  };
+}
+
+export async function runInitWizard(
+  options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    reconfigure?: boolean;
+    prompter?: InitPrompter;
+    isInteractive?: boolean;
+  } = {},
+): Promise<InitWizardResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const reconfigure = options.reconfigure ?? false;
+  const prompter = options.prompter ?? createClackInitPrompter();
+  const current = loadConfig({ cwd, env });
+  const stored = readPersistedConfig({ cwd, env });
+
+  const hasStoredGithub = Boolean(stored.data.githubToken);
+  const hasStoredOpenAi = Boolean(stored.data.openaiApiKey);
+  if (!reconfigure && hasStoredGithub && hasStoredOpenAi) {
+    return { configPath: current.configPath, changed: false };
+  }
+
+  const isInteractive = options.isInteractive ?? (process.stdin.isTTY && process.stdout.isTTY);
+  if (!isInteractive) {
+    throw new Error(`ghcrawl init requires a TTY. Create ${current.configPath} manually or set environment variables first.`);
+  }
+
+  await prompter.intro('ghcrawl init');
+  await prompter.note(
+    [
+      `Config file: ${current.configPath}`,
+      '',
+      'Secret storage modes:',
+      '- Plaintext config: writes both keys to ~/.config/ghcrawl/config.json',
+      '- 1Password CLI: keeps keys out of the config file and expects you to run ghcrawl through an op wrapper',
+      '',
+      'GitHub token recommendation:',
+      '- Fine-grained PAT scoped to the repos you want to crawl',
+      '- Repository permissions: Metadata (read), Issues (read), Pull requests (read)',
+      '- For private repos with a classic PAT, repo is the safe fallback',
+      '',
+      'OpenAI key recommendation:',
+      '- Standard API key for the project/account you want to bill',
+    ].join('\n'),
+    'Setup',
+  );
+
+  const nextConfig = { ...stored.data };
+  let changed = false;
+
+  const secretMode = await prompter.select({
+    message: 'How should ghcrawl get your GitHub and OpenAI secrets?',
+    initialValue: stored.data.secretProvider ?? (hasStoredGithub && hasStoredOpenAi ? 'plaintext' : 'op'),
+    options: [
+      {
+        value: 'plaintext',
+        label: 'Store plaintext keys in ~/.config/ghcrawl/config.json',
+        hint: 'simpler, but you are responsible for any bills caused by misuse',
+      },
+      {
+        value: 'op',
+        label: 'Keep keys in 1Password CLI and run through op',
+        hint: 'recommended if you already use op',
+      },
+    ],
+  });
+  if (isCancel(secretMode) || (secretMode !== 'plaintext' && secretMode !== 'op')) {
+    prompter.cancel('init cancelled');
+    throw new Error('init cancelled');
+  }
+
+  if (secretMode === 'plaintext') {
+    await prompter.note(
+      [
+        'Plaintext storage warning:',
+        '- ghcrawl will write both API keys to ~/.config/ghcrawl/config.json',
+        '- anyone who can read that file can use your keys',
+        '- any OpenAI/API bills caused by misuse are your responsibility',
+      ].join('\n'),
+      'Security',
+    );
+
+    if (reconfigure || !hasStoredGithub) {
+      const detectedGithub = env.GITHUB_TOKEN;
+      let githubToken = stored.data.githubToken;
+      let usedDetectedGithub = false;
+      if (detectedGithub && (!githubToken || reconfigure)) {
+        const useDetected = await prompter.confirm({
+          message: 'Persist the detected GITHUB_TOKEN environment value to the ghcrawl config file?',
+          initialValue: true,
+        });
+        if (isCancel(useDetected)) {
+          prompter.cancel('init cancelled');
+          throw new Error('init cancelled');
+        }
+        if (useDetected) {
+          if (isLikelyGitHubToken(detectedGithub)) {
+            githubToken = detectedGithub;
+            usedDetectedGithub = true;
+          } else {
+            await prompter.note('The detected GITHUB_TOKEN value does not look like a GitHub PAT, so init will prompt for it instead.', 'GitHub token');
+          }
+        }
+      }
+      if (!githubToken || (reconfigure && !usedDetectedGithub)) {
+        const value = await prompter.password({
+          message: 'GitHub personal access token',
+          validate: (candidate) => (isLikelyGitHubToken(candidate) ? undefined : 'Enter a GitHub PAT like ghp_... or github_pat_...'),
+        });
+        if (isCancel(value)) {
+          prompter.cancel('init cancelled');
+          throw new Error('init cancelled');
+        }
+        githubToken = value;
+      }
+      nextConfig.githubToken = githubToken;
+      changed = true;
+    }
+
+    if (reconfigure || !hasStoredOpenAi) {
+      const detectedOpenAi = env.OPENAI_API_KEY;
+      let openaiApiKey = stored.data.openaiApiKey;
+      let usedDetectedOpenAi = false;
+      if (detectedOpenAi && (!openaiApiKey || reconfigure)) {
+        const useDetected = await prompter.confirm({
+          message: 'Persist the detected OPENAI_API_KEY environment value to the ghcrawl config file?',
+          initialValue: true,
+        });
+        if (isCancel(useDetected)) {
+          prompter.cancel('init cancelled');
+          throw new Error('init cancelled');
+        }
+        if (useDetected) {
+          if (isLikelyOpenAiApiKey(detectedOpenAi)) {
+            openaiApiKey = detectedOpenAi;
+            usedDetectedOpenAi = true;
+          } else {
+            await prompter.note('The detected OPENAI_API_KEY value does not look like an OpenAI API key, so init will prompt for it instead.', 'OpenAI key');
+          }
+        }
+      }
+      if (!openaiApiKey || (reconfigure && !usedDetectedOpenAi)) {
+        const value = await prompter.password({
+          message: 'OpenAI API key',
+          validate: (candidate) => (isLikelyOpenAiApiKey(candidate) ? undefined : 'Enter an OpenAI API key like sk-...'),
+        });
+        if (isCancel(value)) {
+          prompter.cancel('init cancelled');
+          throw new Error('init cancelled');
+        }
+        openaiApiKey = value;
+      }
+      nextConfig.openaiApiKey = openaiApiKey;
+      changed = true;
+    }
+
+    nextConfig.secretProvider = 'plaintext';
+    nextConfig.opVaultName = undefined;
+    nextConfig.opItemName = undefined;
+  } else {
+    const defaultVaultName = stored.data.opVaultName ?? 'Private';
+    const vaultNameInput = await prompter.text({
+      message: '1Password vault name',
+      placeholder: defaultVaultName,
+    });
+    const vaultName = resolveTextValue(vaultNameInput, defaultVaultName);
+    if (isCancel(vaultName)) {
+      prompter.cancel('init cancelled');
+      throw new Error('init cancelled');
+    }
+    const defaultItemName = stored.data.opItemName ?? 'ghcrawl';
+    const itemNameInput = await prompter.text({
+      message: '1Password item name',
+      placeholder: defaultItemName,
+    });
+    const itemName = resolveTextValue(itemNameInput, defaultItemName);
+    if (isCancel(itemName)) {
+      prompter.cancel('init cancelled');
+      throw new Error('init cancelled');
+    }
+
+    nextConfig.secretProvider = 'op';
+    nextConfig.opVaultName = vaultName.trim();
+    nextConfig.opItemName = itemName.trim();
+    nextConfig.githubToken = undefined;
+    nextConfig.openaiApiKey = undefined;
+    changed = true;
+
+    const opReferenceBase = `op://${nextConfig.opVaultName}/${nextConfig.opItemName}`;
+    await prompter.note(
+      [
+        'Create a 1Password Secure Note with:',
+        `- Vault: ${nextConfig.opVaultName}`,
+        `- Item: ${nextConfig.opItemName}`,
+        '',
+        'Add concealed fields named exactly:',
+        '- GITHUB_TOKEN',
+        '- OPENAI_API_KEY',
+        '',
+        'Secret refs:',
+        `- ${opReferenceBase}/GITHUB_TOKEN`,
+        `- ${opReferenceBase}/OPENAI_API_KEY`,
+      ].join('\n'),
+      '1Password Setup',
+    );
+    const readyNote = await prompter.confirm({
+      message: 'I created the Secure Note with those exact field names and secret refs.',
+      initialValue: true,
+    });
+    if (isCancel(readyNote) || readyNote !== true) {
+      prompter.cancel('init cancelled');
+      throw new Error('init cancelled');
+    }
+
+    await prompter.note(
+      [
+        'After saving that Secure Note, run ghcrawl through an op-backed shell helper:',
+        '',
+        'ghcrawl-op() {',
+        `  env GITHUB_TOKEN=\"$(op read '${opReferenceBase}/GITHUB_TOKEN')\" \\`,
+        `      OPENAI_API_KEY=\"$(op read '${opReferenceBase}/OPENAI_API_KEY')\" \\`,
+        '      ghcrawl "$@"',
+        '}',
+        '',
+        'Examples:',
+        '- ghcrawl-op doctor',
+        '- ghcrawl-op tui',
+        '- ghcrawl-op sync org/repo',
+      ].join('\n'),
+      'Next Commands',
+    );
+    const readyCommands = await prompter.confirm({
+      message: 'I copied those commands and I am ready to save this ghcrawl config.',
+      initialValue: true,
+    });
+    if (isCancel(readyCommands) || readyCommands !== true) {
+      prompter.cancel('init cancelled');
+      throw new Error('init cancelled');
+    }
+  }
+
+  await prompter.note(
+    [
+      'Responsibility attestation:',
+      '- You are responsible for obtaining and using GitHub and OpenAI API keys in compliance with the agreements and usage policies for those platforms.',
+      '- You and any employer or organization you operate this tool for accept full responsibility for monitoring API usage, spend, and access.',
+      '- You are fully responsible for storing your API keys securely and for any misuse, theft, or unexpected spend caused by those keys.',
+      '- The creators and contributors of ghcrawl accept no liability for API charges, account actions, data loss, or misuse resulting from operation of this tool.',
+    ].join('\n'),
+    'Responsibility',
+  );
+  const acceptResponsibility = await prompter.confirm({
+    message: 'I understand and accept full responsibility for using ghcrawl and for securing any API keys it uses.',
+    initialValue: false,
+  });
+  if (isCancel(acceptResponsibility) || acceptResponsibility !== true) {
+    prompter.cancel('init cancelled');
+    throw new Error('init cancelled');
+  }
+
+  const result = writePersistedConfig(nextConfig, { cwd, env });
+  await prompter.outro(`Saved ghcrawl config to ${result.configPath}`);
+  return { configPath: result.configPath, changed };
+}