@nomos-arc/arc 0.1.0

package/src/commands/auth.ts

@@ -0,0 +1,301 @@
+import * as path from 'node:path';
+import type { Command } from 'commander';
+import * as readline from 'node:readline';
+import { OAuth2Client } from 'google-auth-library';
+import { loadConfig } from '../core/config.js';
+import { createLogger } from '../core/logger.js';
+import { NomosError } from '../core/errors.js';
+import { AuthManager } from '../core/auth/manager.js';
+import { startLoopbackServer } from '../core/auth/server.js';
+import { listGcpProjects, promptProjectSelection, verifyGeminiAccess } from '../core/auth/gcp-projects.js';
+
+const SCOPES = [
+  'https://www.googleapis.com/auth/generative-language',
+  'https://www.googleapis.com/auth/cloud-platform.read-only',
+];
+
+/**
+ * Prompt the user for a secret value with masked input (shows * characters).
+ * Used as last-resort fallback when client_secret is not in config or env.
+ */
+async function promptSecret(prompt: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    // Mask input by writing * for each character
+    process.stdout.write(prompt);
+    let secret = '';
+    process.stdin.setRawMode?.(true);
+    process.stdin.resume();
+    process.stdin.on('data', (char: Buffer) => {
+      const c = char.toString('utf8');
+      if (c === '\n' || c === '\r') {
+        process.stdin.setRawMode?.(false);
+        rl.close();
+        process.stdout.write('\n');
+        resolve(secret);
+      } else if (c === '\u0003') { // Ctrl+C
+        process.stdin.setRawMode?.(false);
+        rl.close();
+        process.exit(1);
+      } else if (c === '\u007f') { // Backspace
+        if (secret.length > 0) {
+          secret = secret.slice(0, -1);
+          process.stdout.write('\b \b');
+        }
+      } else {
+        secret += c;
+        process.stdout.write('*');
+      }
+    });
+  });
+}
+
+export function registerAuthCommand(program: Command): void {
+  const auth = program
+    .command('auth')
+    .description('Manage Google OAuth authentication');
+
+  // ─── arc auth login ──────────────────────────────────────────────
+  auth
+    .command('login')
+    .description('Authenticate with Google via OAuth 2.0 and select a GCP billing project')
+    .option('--client-id <id>', 'Google OAuth client ID')
+    .option('--project <id>', 'GCP project ID for Gemini API quota (skip interactive picker)')
+    .action(async (opts) => {
+      try {
+        // 1. Load project config
+        const { config, projectRoot } = loadConfig();
+        const logDir = path.join(projectRoot, 'tasks-management', 'logs');
+        const logger = createLogger(config.logging.level, logDir);
+
+        // 2. Resolve clientId: CLI flag > config file
+        const clientId = opts.clientId ?? config.auth.client_id;
+        if (!clientId) {
+          throw new NomosError(
+            'auth_client_config_missing',
+            'Google OAuth client_id not found. Provide via --client-id flag or set auth.client_id in .nomos-config.json',
+          );
+        }
+
+        // 3. Resolve clientSecret: env var > interactive prompt
+        //    SECURITY: client_secret is NOT read from .nomos-config.json (project config is committed to git).
+        //    NOTE: --client-secret CLI flag intentionally NOT supported (F-001: leaks to shell history / ps).
+        let clientSecret = process.env['NOMOS_GOOGLE_CLIENT_SECRET'];
+        if (!clientSecret) {
+          logger.info('[nomos:auth:info] Client secret not found in environment (NOMOS_GOOGLE_CLIENT_SECRET).');
+          clientSecret = await promptSecret('Enter Google OAuth client secret: ');
+          if (!clientSecret) {
+            throw new NomosError(
+              'auth_client_config_missing',
+              'Google OAuth client_secret not provided. Set NOMOS_GOOGLE_CLIENT_SECRET env var or enter it at the prompt.',
+            );
+          }
+        }
+
+        // 4. Create OAuth2Client
+        const oauth2Client = new OAuth2Client({ clientId, clientSecret });
+
+        // 5. Create AuthManager
+        const authManager = new AuthManager(config.auth, logger);
+
+        // 6. Start loopback server, open browser, wait for callback
+        console.log('Opening browser for Google authentication...');
+        const tokens = await startLoopbackServer(
+          oauth2Client, SCOPES, config.auth.redirect_port, logger,
+        );
+
+        // 7. Save credentials immediately (so login persists even if project selection fails)
+        tokens.client_id = clientId;
+        tokens.client_secret = clientSecret;
+        await authManager.saveCredentials(tokens);
+        console.log('✓ Authenticated successfully.\n');
+
+        // 8. GCP Project Selection
+        let quotaProjectId: string | undefined;
+
+        if (opts.project) {
+          // --project flag: skip interactive picker
+          quotaProjectId = opts.project;
+          console.log(`Using project from --project flag: ${quotaProjectId}`);
+        } else {
+          // Fetch user's GCP projects and let them pick
+          console.log('Fetching your Google Cloud projects...');
+          try {
+            const projects = await listGcpProjects(tokens.access_token);
+
+            if (projects.length === 0) {
+              console.log('No active GCP projects found. Skipping project selection.');
+              console.log('You can set a project later with: arc auth set-project <PROJECT_ID>');
+            } else if (projects.length === 1) {
+              quotaProjectId = projects[0]!.projectId;
+              console.log(`Auto-selected project: ${projects[0]!.displayName} (${quotaProjectId})`);
+            } else {
+              quotaProjectId = await promptProjectSelection(projects);
+            }
+          } catch (err) {
+            if (err instanceof NomosError) {
+              console.error(`[nomos:warn] ${err.message}`);
+              console.log('You can set a project later with: arc auth set-project <PROJECT_ID>');
+            } else {
+              throw err;
+            }
+          }
+        }
+
+        // 9. Verify Gemini API access on the selected project
+        if (quotaProjectId) {
+          try {
+            console.log(`\nVerifying Gemini API access on project "${quotaProjectId}"...`);
+            await verifyGeminiAccess(tokens.access_token, quotaProjectId);
+            console.log('✓ Gemini API is accessible.\n');
+          } catch (err) {
+            if (err instanceof NomosError && err.code === 'auth_gemini_not_enabled') {
+              console.error(`\n[nomos:warn] ${err.message}`);
+              console.log('\nLogin saved without project. After enabling the API, run: arc auth set-project ' + quotaProjectId);
+              quotaProjectId = undefined;
+            } else {
+              throw err;
+            }
+          }
+        }
+
+        // 10. Re-save credentials with quota_project_id
+        tokens.quota_project_id = quotaProjectId;
+        await authManager.saveCredentials(tokens);
+
+        // 11. Final confirmation
+        console.log(`Credentials saved to ${config.auth.credentials_path}`);
+        if (quotaProjectId) {
+          console.log(`Quota project: ${quotaProjectId}`);
+        }
+        console.log('\n✓ Auth complete.');
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+
+  // ─── arc auth set-project ────────────────────────────────────────
+  auth
+    .command('set-project <projectId>')
+    .description('Set or change the GCP project for Gemini API billing')
+    .action(async (projectId: string) => {
+      try {
+        const { config, projectRoot } = loadConfig();
+        const logDir = path.join(projectRoot, 'tasks-management', 'logs');
+        const logger = createLogger(config.logging.level, logDir);
+        const authManager = new AuthManager(config.auth, logger);
+
+        const creds = authManager.loadCredentials();
+        if (!creds) {
+          throw new NomosError('auth_not_logged_in', 'Not logged in. Run `arc auth login` first.');
+        }
+
+        // Verify Gemini API access
+        const token = await authManager.getAccessToken();
+        console.log(`Verifying Gemini API access on project "${projectId}"...`);
+        await verifyGeminiAccess(token, projectId);
+        console.log('✓ Gemini API is accessible.\n');
+
+        // Update credentials
+        creds.quota_project_id = projectId;
+        await authManager.saveCredentials(creds);
+        console.log(`✓ Quota project set to "${projectId}".`);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+
+  // ─── arc auth logout ─────────────────────────────────────────────
+  auth
+    .command('logout')
+    .description('Remove stored OAuth credentials')
+    .action(async () => {
+      try {
+        // 1. Load config, create AuthManager
+        const { config, projectRoot } = loadConfig();
+        const logDir = path.join(projectRoot, 'tasks-management', 'logs');
+        const logger = createLogger(config.logging.level, logDir);
+        const authManager = new AuthManager(config.auth, logger);
+
+        // 2. Delete credentials file
+        await authManager.clearCredentials();
+
+        // 3. Confirm
+        console.log('✓ Logged out. Credentials removed.');
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+
+  // ─── arc auth status ─────────────────────────────────────────────
+  auth
+    .command('status')
+    .description('Show current authentication state')
+    .action(async () => {
+      try {
+        // 1. Load config, create AuthManager
+        const { config, projectRoot } = loadConfig();
+        const logDir = path.join(projectRoot, 'tasks-management', 'logs');
+        const logger = createLogger(config.logging.level, logDir);
+        const authManager = new AuthManager(config.auth, logger);
+
+        // 2. Check login state
+        const loggedIn = authManager.isLoggedIn();
+
+        // 3. If logged in, show token info
+        if (loggedIn) {
+          const creds = authManager.loadCredentials()!;
+          const expiryDate = new Date(creds.expiry_date);
+          const isExpired = creds.expiry_date < Date.now();
+          console.log(`OAuth: Logged in (token ${isExpired ? 'EXPIRED' : 'valid until ' + expiryDate.toLocaleString()})`);
+
+          // 4. Show quota project
+          if (creds.quota_project_id) {
+            console.log(`GCP Billing Project: ${creds.quota_project_id}`);
+          } else {
+            console.log('GCP Billing Project: Not set (run `arc auth login` or `arc auth set-project <ID>`)');
+          }
+        } else {
+          console.log('OAuth: Not logged in');
+        }
+
+        // 5. Check API key
+        const hasApiKey = !!process.env['GEMINI_API_KEY'];
+        console.log(`API Key: ${hasApiKey ? 'Set (GEMINI_API_KEY)' : 'Not set'}`);
+
+        // 6. Show credential chain resolution
+        if (hasApiKey) {
+          console.log('Active credential: GEMINI_API_KEY (takes priority over OAuth)');
+        } else if (loggedIn) {
+          console.log('Active credential: OAuth access token');
+        } else {
+          console.log('Active credential: None — run `arc auth login` or set GEMINI_API_KEY');
+        }
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/certificate.ts

@@ -0,0 +1,89 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { CertificateEngine } from '../core/certificate.js';
+import { NomosError } from '../core/errors.js';
+
+export function registerCertificateCommand(program: Command): void {
+  program
+    .command('certificate <task>')
+    .description('Generate or verify a Certificate of AI Engineering Integrity')
+    .option('--output <path>', 'Output path for the certificate file')
+    .option('--format <fmt>', 'Output format', 'json')
+    .option('--verify', 'Verify an existing certificate instead of generating')
+    .action(async (task: string, opts: { output?: string; format: string; verify?: boolean }) => {
+      try {
+        const { orchestrator, projectRoot } = await createOrchestrator();
+        const engine = new CertificateEngine();
+
+        const defaultPath = path.join(
+          projectRoot, 'tasks-management', 'certificates', `${task}.certificate.json`,
+        );
+        const certPath = opts.output ?? defaultPath;
+
+        if (opts.verify) {
+          // ── Verify mode ──────────────────────────────────────────────
+          if (!fs.existsSync(certPath)) {
+            throw new NomosError(
+              'certificate_not_found',
+              `Certificate file not found: ${certPath}`,
+            );
+          }
+
+          const raw = fs.readFileSync(certPath, 'utf-8');
+          const certificate = engine.parse(raw);
+          const result = engine.verify(certificate);
+
+          console.log(`\nCertificate Verification: ${task}`);
+          console.log('─'.repeat(50));
+
+          for (const check of result.checks) {
+            const icon = check.passed ? 'PASS' : 'FAIL';
+            console.log(`  [${icon}] ${check.name}`);
+            console.log(`         ${check.detail}`);
+          }
+
+          console.log('─'.repeat(50));
+          console.log(`Result: ${result.valid ? 'VALID' : 'INVALID'}`);
+
+          process.exit(result.valid ? 0 : 1);
+        }
+
+        // ── Generate mode ────────────────────────────────────────────
+        const state = await orchestrator.status(task);
+        const certificate = engine.generate(state);
+
+        // Ensure output directory exists
+        fs.mkdirSync(path.dirname(certPath), { recursive: true });
+        fs.writeFileSync(certPath, JSON.stringify(certificate, null, 2), 'utf-8');
+
+        const finalScore = certificate.final_review.score;
+        const iterCount = certificate.iterations.length;
+
+        console.log(
+          `\nCertificate Generated\n` +
+          `─`.repeat(50) + `\n` +
+          `Task:            ${certificate.task_id}\n` +
+          `Status:          ${certificate.task_status}\n` +
+          `Iterations:      ${iterCount}\n` +
+          `Final Score:     ${finalScore.toFixed(2)}\n` +
+          `Approval:        ${certificate.final_review.approval_reason}\n` +
+          `Chain Hash:      ${certificate.integrity.chain_hash}\n` +
+          `Certificate:     ${certificate.certificate_hash}\n` +
+          `─`.repeat(50) + `\n` +
+          `Saved to: ${certPath}\n` +
+          `\nVerify with: arc certificate ${task} --verify`,
+        );
+
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/discard.ts

@@ -0,0 +1,24 @@
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { NomosError } from '../core/errors.js';
+
+export function registerDiscardCommand(program: Command): void {
+  program
+    .command('discard <task>')
+    .description('Discard a task: remove worktree, delete shadow branch, and mark as discarded')
+    .action(async (task: string) => {
+      try {
+        const { orchestrator } = await createOrchestrator();
+        await orchestrator.discard(task);
+        console.log(`Task '${task}' discarded.`);
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/drift.ts

@@ -0,0 +1,116 @@
+import * as path from 'node:path';
+import type { Command } from 'commander';
+import { simpleGit } from 'simple-git';
+import { loadConfig } from '../core/config.js';
+import { createLogger } from '../core/logger.js';
+import { NomosError } from '../core/errors.js';
+import { readProjectMap, migrateProjectMap } from '../core/graph/map-schema.js';
+import { compare } from '../core/graph/drift/comparator.js';
+import { classify } from '../core/graph/drift/classifier.js';
+import { render } from '../core/graph/drift/reporter.js';
+
+export function registerDriftCommand(program: Command): void {
+  program
+    .command('drift')
+    .description('Detect structural drift between the current project map and a baseline')
+    .option('--baseline <path>', 'Path to a baseline project_map.json file')
+    .option('--json', 'Output drift report as JSON', false)
+    .option('--breaking-only', 'Only report breaking changes', false)
+    .action(
+      async (opts: { baseline?: string; json: boolean; breakingOnly: boolean }) => {
+        const { config, projectRoot } = loadConfig();
+        const logDir = path.join(projectRoot, 'tasks-management', 'logs');
+        const logger = createLogger(config.logging.level, logDir);
+
+        const currentMapPath = path.join(
+          projectRoot,
+          config.graph.output_dir,
+          'project_map.json',
+        );
+
+        // ── Step 3: Resolve baseline map ────────────────────────────────────────
+        let baseline;
+
+        if (opts.baseline) {
+          // --baseline <path> provided: read from file
+          const result = await readProjectMap(opts.baseline);
+          if (result === null) {
+            throw new NomosError(
+              'drift_baseline_not_found',
+              `Baseline map not found at '${opts.baseline}'. Ensure the file exists and is readable.`,
+            );
+          }
+          baseline = result;
+        } else {
+          // No --baseline: read HEAD:project_map.json from git history
+          const git = simpleGit(projectRoot);
+          const relativeMapPath = path.relative(projectRoot, currentMapPath).split(path.sep).join('/');
+
+          let rawGitContent: string;
+          try {
+            rawGitContent = await git.show([`HEAD:${relativeMapPath}`]);
+          } catch {
+            throw new NomosError(
+              'drift_baseline_not_found',
+              'No baseline map found. Commit a project_map.json first, or use --baseline <path>.',
+            );
+          }
+
+          let parsedBaseline: unknown;
+          try {
+            parsedBaseline = JSON.parse(rawGitContent);
+          } catch {
+            throw new NomosError(
+              'drift_parse_error',
+              'Baseline map from git history is not valid JSON. Ensure the committed project_map.json is well-formed.',
+            );
+          }
+
+          baseline = migrateProjectMap(parsedBaseline);
+        }
+
+        // ── Step 4: Load current map ─────────────────────────────────────────────
+        const current = await readProjectMap(currentMapPath);
+        if (current === null) {
+          throw new NomosError(
+            'graph_map_not_found',
+            'No current project map. Run: arc map',
+          );
+        }
+
+        // ── Steps 5-7: Compare → Classify → Render ───────────────────────────────
+        logger.debug('Running drift comparison...');
+        const report = compare(baseline, current);
+        const classified = classify(report);
+        const output = render(classified, baseline.generated_at, current.generated_at, {
+          json: opts.json,
+          breakingOnly: opts.breakingOnly,
+        });
+
+        // ── Step 8: Output ────────────────────────────────────────────────────────
+        console.log(output);
+
+        // ── Step 9: Exit code — DO NOT call process.exit() (ref: F-001) ──────────
+        // process.exitCode is set and main() in cli.ts handles termination.
+        const s = report.summary;
+        const hasAnything =
+          s.files_added > 0 ||
+          s.files_removed > 0 ||
+          s.files_modified > 0 ||
+          s.symbols_added > 0 ||
+          s.symbols_removed > 0 ||
+          s.symbols_changed > 0 ||
+          s.imports_added > 0 ||
+          s.imports_removed > 0 ||
+          s.depth_changes > 0 ||
+          s.stale_enrichments > 0;
+
+        if (classified.has_breaking) {
+          process.exitCode = 3;
+        } else if (hasAnything) {
+          process.exitCode = 2;
+        }
+        // else: default exitCode = 0 (no drift)
+      },
+    );
+}

package/src/commands/index.ts

@@ -0,0 +1,78 @@
+import * as path from 'node:path';
+import type { Command } from 'commander';
+import { loadConfig } from '../core/config.js';
+import { createLogger } from '../core/logger.js';
+import { NomosError } from '../core/errors.js';
+import { SearchIndexer } from '../search/indexer.js';
+import { AuthManager } from '../core/auth/manager.js';
+
+export function registerIndexCommand(program: Command): void {
+  program
+    .command('index')
+    .description('Build or rebuild the vector search index from project map')
+    .option('--incremental', 'Only re-index files changed since last indexing run')
+    .option('--force', 'Force full re-index (ignore incremental metadata)')
+    .option('--dry-run', 'Count chunks without embedding (no API calls, no writes)')
+    .action(async (opts: { incremental?: boolean; force?: boolean; dryRun?: boolean }) => {
+      try {
+        const { config, projectRoot } = loadConfig();
+        const logDir = path.join(projectRoot, 'tasks-management', 'logs');
+        const logger = createLogger(config.logging.level, logDir);
+        const authManager = new AuthManager(config.auth, logger);
+        const indexer = new SearchIndexer(projectRoot, config, logger, authManager);
+
+        // --dry-run: count chunks only, no API calls, no writes [S-2]
+        if (opts.dryRun) {
+          logger.info('[nomos:search:info] DRY RUN — no API calls, no writes.');
+          const { fileChunks, symbolChunks, totalChunks } = await indexer.dryRun();
+          const batchSize = config.search.batch_size;
+          const batchCount = Math.ceil(totalChunks / batchSize);
+          logger.info(
+            `[nomos:search:info] Would index: ${totalChunks} chunks (${fileChunks} file-level, ${symbolChunks} symbol-level)`,
+          );
+          logger.info(
+            `[nomos:search:info] Estimated API calls: ${batchCount} batches × ${batchSize} chunks`,
+          );
+          process.exit(0);
+        }
+
+        const cancellationFlag = { cancelled: false };
+
+        process.on('SIGINT', () => {
+          cancellationFlag.cancelled = true;
+          logger.warn('[nomos:search:warn] SIGINT received. Finishing current batch...');
+        });
+
+        logger.info('[nomos:search:info] Extracting chunks from project map...');
+
+        const startTime = Date.now();
+
+        // --incremental (without --force) → incremental index; everything else → full index
+        const meta = (opts.incremental && !opts.force)
+          ? await indexer.incrementalIndex(cancellationFlag)
+          : await indexer.fullIndex(cancellationFlag);
+
+        const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+        console.log(
+          `Indexed ${meta.total_chunks} chunks (${meta.total_files_indexed} files, ${meta.total_symbols_indexed} symbols) in ${duration}s`,
+        );
+        console.log(`Vector index stored at: ${config.search.vector_store_path}`);
+
+        if (meta.failed_files.length > 0) {
+          console.error(
+            `⚠ ${meta.failed_files.length} files failed embedding. They will be retried on next incremental index.`,
+          );
+        }
+
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}