@gitpagedocs/tools 1.1.44

package/src/index.ts

@@ -0,0 +1,24 @@
+// @gitpagedocs/tools — shared business-logic core.
+//
+// The single home for domain logic consumed by the frontend, the CLI and the
+// MCP server. Consumers import from here (or subpath modules) and depend on the
+// port interfaces, never on concrete adapters they don't need.
+
+// Port contracts (type-only).
+export type * from "./ports";
+
+// Phase 4 — cross-cutting core implementations.
+export * from "./errors";
+export * from "./logger";
+export * from "./crypto";
+export * from "./cache";
+export * from "./security";
+export * from "./config";
+export * from "./constants";
+
+// Phase 5 — shared AI system.
+export * from "./ai";
+
+// Phase 7 — filesystem + documentation services.
+export * from "./filesystem";
+export * from "./documentation";

package/src/logger/index.ts

@@ -0,0 +1,2 @@
+export * from "./logger";
+export { redact, redactFields, REDACTED } from "./redaction";

package/src/logger/logger.ts

@@ -0,0 +1,73 @@
+import type { Logger, LogFields, LogLevel, LogSink } from "../ports/logger";
+import { redact, redactFields } from "./redaction";
+
+const LEVEL_ORDER: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+export interface LoggerOptions {
+  readonly level?: LogLevel;
+  readonly sink?: LogSink;
+  readonly baseFields?: LogFields;
+}
+
+/** Sink that writes redacted records to the console. */
+export class ConsoleSink implements LogSink {
+  write(level: LogLevel, message: string, fields: LogFields): void {
+    const safeMessage = redact(message) as string;
+    const hasFields = Object.keys(fields).length > 0;
+    const payload = hasFields ? redactFields(fields as Record<string, unknown>) : undefined;
+    const line = `[${level}] ${safeMessage}`;
+    if (level === "error") console.error(line, payload ?? "");
+    else if (level === "warn") console.warn(line, payload ?? "");
+    else console.log(line, payload ?? "");
+  }
+}
+
+/** Discards all records (useful for tests / silent CLI runs). */
+export class NullSink implements LogSink {
+  write(): void {
+    /* no-op */
+  }
+}
+
+class StandardLogger implements Logger {
+  private readonly level: LogLevel;
+  private readonly sink: LogSink;
+  private readonly baseFields: LogFields;
+
+  constructor(options: LoggerOptions) {
+    this.level = options.level ?? "info";
+    this.sink = options.sink ?? new ConsoleSink();
+    this.baseFields = options.baseFields ?? {};
+  }
+
+  private emit(level: LogLevel, message: string, fields?: LogFields): void {
+    if (LEVEL_ORDER[level] < LEVEL_ORDER[this.level]) return;
+    const merged = fields ? { ...this.baseFields, ...fields } : this.baseFields;
+    this.sink.write(level, message, merged);
+  }
+
+  debug(message: string, fields?: LogFields): void {
+    this.emit("debug", message, fields);
+  }
+  info(message: string, fields?: LogFields): void {
+    this.emit("info", message, fields);
+  }
+  warn(message: string, fields?: LogFields): void {
+    this.emit("warn", message, fields);
+  }
+  error(message: string, fields?: LogFields): void {
+    this.emit("error", message, fields);
+  }
+
+  child(fields: LogFields): Logger {
+    return new StandardLogger({
+      level: this.level,
+      sink: this.sink,
+      baseFields: { ...this.baseFields, ...fields },
+    });
+  }
+}
+
+export function createLogger(options: LoggerOptions = {}): Logger {
+  return new StandardLogger(options);
+}

package/src/logger/redaction.ts

@@ -0,0 +1,43 @@
+/**
+ * Secret redaction. Applied to every log record before it reaches a sink so
+ * API keys and other credentials can never appear in logs.
+ */
+const SENSITIVE_KEY_PATTERN = /(api[_-]?key|secret|token|password|passwd|authorization|bearer|x-api-key)/i;
+
+/** Token-like values: long opaque strings, optionally with a provider prefix. */
+const TOKEN_VALUE_PATTERN = /\b((?:sk|pk|gsk|xai|or|hf|ghp|gho|github_pat|AIza)[-_][A-Za-z0-9-_]{8,}|[A-Za-z0-9-_]{32,})\b/g;
+
+export const REDACTED = "[REDACTED]";
+
+/** Mask a string value, keeping a short, non-reversible hint. */
+function maskValue(value: string): string {
+  if (value.length <= 8) return REDACTED;
+  return `${value.slice(0, 3)}…${value.slice(-4)}`;
+}
+
+function redactString(input: string): string {
+  return input.replace(TOKEN_VALUE_PATTERN, (match) => maskValue(match));
+}
+
+/** Recursively redact a value: sensitive keys are masked, strings scrubbed. */
+export function redact(value: unknown, keyHint?: string): unknown {
+  if (typeof value === "string") {
+    if (keyHint && SENSITIVE_KEY_PATTERN.test(keyHint)) return maskValue(value);
+    return redactString(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redact(item));
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = SENSITIVE_KEY_PATTERN.test(k) && typeof v === "string" ? maskValue(v) : redact(v, k);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function redactFields(fields: Record<string, unknown>): Record<string, unknown> {
+  return redact(fields) as Record<string, unknown>;
+}

package/src/ports/ai.ts

@@ -0,0 +1,109 @@
+/**
+ * AI ports (Strategy + Registry + Factory). Implemented in Phase 5 in
+ * tools/src/ai, unifying the current browser (src/features/ask-ai) and CLI
+ * (src/cli/infrastructure/llm) provider implementations behind one contract.
+ */
+export type AiProviderId =
+  | "openai"
+  | "anthropic"
+  | "gemini"
+  | "openrouter"
+  | "ollama"
+  | "azure-openai"
+  | "mistral"
+  | "deepseek"
+  | "cohere"
+  | "groq"
+  | "xai"
+  | "together"
+  | "fireworks"
+  | "perplexity";
+
+export type AiRole = "system" | "user" | "assistant";
+
+export interface AiAttachment {
+  readonly kind: "image" | "audio";
+  readonly mimeType: string;
+  /** Base64-encoded data. */
+  readonly data: string;
+}
+
+export interface AiMessage {
+  readonly role: AiRole;
+  readonly content: string;
+  readonly attachments?: readonly AiAttachment[];
+}
+
+export interface ModelDescriptor {
+  readonly id: string;
+  readonly label?: string;
+  readonly contextWindow?: number;
+  readonly supportsStreaming?: boolean;
+  readonly supportsVision?: boolean;
+  readonly supportsAudio?: boolean;
+}
+
+export interface ProviderConfig {
+  readonly providerId: AiProviderId;
+  readonly model: string;
+  readonly apiKey?: string;
+  /** For self-hosted/proxy providers (e.g. Ollama, Azure). */
+  readonly baseUrl?: string;
+  readonly extraHeaders?: Readonly<Record<string, string>>;
+}
+
+export interface GenerateRequest {
+  readonly messages: readonly AiMessage[];
+  readonly system?: string;
+  readonly temperature?: number;
+  readonly maxTokens?: number;
+  readonly signal?: AbortSignal;
+}
+
+export interface GenerateResponse {
+  readonly text: string;
+  readonly model: string;
+  readonly finishReason?: string;
+}
+
+/** Streaming responses surface as an async iterable of text deltas. */
+export type StreamResponse = AsyncIterable<string>;
+
+export interface ProviderCapabilities {
+  readonly streaming: boolean;
+  readonly vision: boolean;
+  readonly audio: boolean;
+}
+
+/** A single provider strategy. */
+export interface AIProvider {
+  readonly id: AiProviderId;
+  readonly capabilities: ProviderCapabilities;
+  generate(request: GenerateRequest, config: ProviderConfig): Promise<GenerateResponse>;
+  stream(request: GenerateRequest, config: ProviderConfig): StreamResponse;
+}
+
+/** Provider metadata + factory registration (Registry pattern). */
+export interface ProviderRegistration {
+  readonly id: AiProviderId;
+  readonly label: string;
+  readonly defaultModel: string;
+  readonly capabilities: ProviderCapabilities;
+  create(): AIProvider;
+}
+
+export interface ProviderRegistry {
+  register(registration: ProviderRegistration): void;
+  has(id: AiProviderId): boolean;
+  get(id: AiProviderId): ProviderRegistration | undefined;
+  list(): readonly ProviderRegistration[];
+}
+
+export interface ProviderFactory {
+  create(id: AiProviderId): AIProvider;
+}
+
+export interface ModelRegistry {
+  list(providerId: AiProviderId): readonly ModelDescriptor[];
+  defaultModel(providerId: AiProviderId): string | undefined;
+}

package/src/ports/cache.ts

@@ -0,0 +1,16 @@
+/**
+ * Cache port (Strategy). Implemented in Phase 4 by MemoryCache, FileCache,
+ * LocalStorageCache and SessionStorageCache.
+ */
+export interface CacheEntryOptions {
+  /** Time-to-live in milliseconds. Omitted = no expiry. */
+  readonly ttlMs?: number;
+}
+
+export interface Cache<TValue = unknown> {
+  get(key: string): Promise<TValue | undefined>;
+  set(key: string, value: TValue, options?: CacheEntryOptions): Promise<void>;
+  has(key: string): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+}

package/src/ports/config.ts

@@ -0,0 +1,21 @@
+/**
+ * Config-loading port. Implemented in Phase 4 by relocating the shared loader
+ * logic currently in src/entities/docs/api/io/config-loader.ts. Must preserve
+ * the legacy CONFIG_EXTENSIONS = [".json", ".js", ".ts"] contract.
+ */
+export type ConfigExtension = ".json" | ".js" | ".ts";
+
+export interface LoadedConfig<TConfig = Record<string, unknown>> {
+  readonly config: TConfig;
+  /** Absolute path the config was resolved from. */
+  readonly sourcePath: string;
+  readonly extension: ConfigExtension;
+}
+
+export interface ConfigLoader {
+  /** Resolve gitpagedocs/config.{json,js,ts} relative to a working directory. */
+  resolveConfigPath(cwd: string): Promise<string | undefined>;
+  loadGitPageDocsConfig<TConfig = Record<string, unknown>>(
+    cwd: string,
+  ): Promise<LoadedConfig<TConfig>>;
+}

package/src/ports/crypto.ts

@@ -0,0 +1,33 @@
+/**
+ * Crypto port. Implemented in Phase 4/5 with Node `crypto` and Web Crypto
+ * adapters. Powers the password-gated, encrypted credential vault.
+ */
+export interface KeyDerivationParams {
+  /** Base64/hex salt. Generated per vault, persisted alongside the ciphertext. */
+  readonly salt: string;
+  /** Iteration count (PBKDF2) or cost parameter (scrypt). */
+  readonly iterations: number;
+}
+
+export interface EncryptedPayload {
+  /** Base64 ciphertext. */
+  readonly ciphertext: string;
+  /** Base64 initialization vector / nonce. */
+  readonly iv: string;
+  /** Authentication tag for AEAD ciphers (base64). */
+  readonly authTag?: string;
+  readonly kdf: KeyDerivationParams;
+}
+
+export interface CryptoService {
+  /** Hex-encoded SHA-256 digest of the input. */
+  sha256(input: string): Promise<string>;
+  /** Derive a symmetric key from a password + KDF params. */
+  deriveKey(password: string, params: KeyDerivationParams): Promise<Uint8Array>;
+  encrypt(plaintext: string, password: string): Promise<EncryptedPayload>;
+  decrypt(payload: EncryptedPayload, password: string): Promise<string>;
+  /** Non-reversible display mask, e.g. "sk-…a1b2" — never reveals the secret. */
+  mask(secret: string): string;
+  /** Best-effort secure wipe of an in-memory buffer. */
+  wipe(buffer: Uint8Array): void;
+}

package/src/ports/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Public port interfaces for @gitpagedocs/tools.
+ *
+ * These are the stable contracts that the frontend, CLI and MCP server consume.
+ * Implementations are added in Phase 4 (core) and Phase 5 (AI + security)
+ * behind these types, so consumers never depend on concrete modules.
+ *
+ * Type-only: importing this file pulls in no runtime code.
+ */
+export type * from "./logger";
+export type * from "./cache";
+export type * from "./crypto";
+export type * from "./security";
+export type * from "./config";
+export type * from "./ai";

package/src/ports/logger.ts

@@ -0,0 +1,23 @@
+/**
+ * Logging port. Implemented in Phase 4 (tools/src/logger).
+ * The implementation MUST redact secrets (API keys) before any sink write.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LogFields {
+  readonly [key: string]: unknown;
+}
+
+export interface Logger {
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+  /** Returns a child logger that merges the given fields into every record. */
+  child(fields: LogFields): Logger;
+}
+
+/** A destination for log records. */
+export interface LogSink {
+  write(level: LogLevel, message: string, fields: LogFields): void;
+}

package/src/ports/security.ts

@@ -0,0 +1,42 @@
+/**
+ * Security ports: password gate + credential vault. Implemented in Phase 5.
+ * Sensitive operations (generate/update docs, analyze, run AI, deploy, run MCP)
+ * must pass through the gate before executing.
+ */
+import type { EncryptedPayload } from "./crypto";
+
+export type SensitiveOperation =
+  | "generate-docs"
+  | "update-docs"
+  | "analyze-project"
+  | "run-ai"
+  | "deploy"
+  | "run-mcp";
+
+export interface StoredCredential {
+  readonly providerId: string;
+  /** Encrypted secret; plaintext is never persisted. */
+  readonly secret: EncryptedPayload;
+  readonly updatedAtIso?: string;
+}
+
+export interface CredentialVault {
+  isInitialized(): Promise<boolean>;
+  /** Establish the local password (first run) and create an empty vault. */
+  initialize(password: string): Promise<void>;
+  unlock(password: string): Promise<boolean>;
+  setCredential(password: string, providerId: string, secret: string): Promise<void>;
+  /** Returns the decrypted secret only when the password is correct. */
+  getCredential(password: string, providerId: string): Promise<string | undefined>;
+  listProviders(): Promise<readonly string[]>;
+  removeCredential(password: string, providerId: string): Promise<void>;
+}
+
+export interface PasswordGate {
+  /**
+   * Authorize a sensitive operation. Implementations prompt for / verify the
+   * local password (one unlock-per-session policy) and throw SecurityError on
+   * failure. Returns the unlock token/password handle for downstream vault use.
+   */
+  authorize(operation: SensitiveOperation): Promise<string>;
+}

package/src/security/credential-vault.ts

@@ -0,0 +1,117 @@
+import type { CredentialVault } from "../ports/security";
+import type { CryptoService, EncryptedPayload } from "../ports/crypto";
+import { SecurityError } from "../errors/app-error";
+
+/** Pluggable persistence for the encrypted vault (file, web storage, …). */
+export interface VaultStorage {
+  load(): Promise<string | null>;
+  save(serialized: string): Promise<void>;
+  /** Permanently remove the stored vault (used by a password reset). */
+  clear(): Promise<void>;
+}
+
+interface VaultFile {
+  readonly version: 1;
+  /** Encrypts a fixed sentinel so a password can be verified before use. */
+  readonly verifier: EncryptedPayload;
+  readonly credentials: Record<string, EncryptedPayload>;
+}
+
+const SENTINEL = "gitpagedocs::vault::v1";
+
+/**
+ * Password-encrypted credential store. Plaintext secrets are never persisted;
+ * every secret is sealed with AES-256-GCM under a PBKDF2-derived key.
+ */
+export class EncryptedCredentialVault implements CredentialVault {
+  private file?: VaultFile;
+
+  constructor(
+    private readonly storage: VaultStorage,
+    private readonly crypto: CryptoService,
+  ) {}
+
+  private async read(): Promise<VaultFile | undefined> {
+    if (this.file) return this.file;
+    const raw = await this.storage.load();
+    if (!raw) return undefined;
+    this.file = JSON.parse(raw) as VaultFile;
+    return this.file;
+  }
+
+  private async write(file: VaultFile): Promise<void> {
+    this.file = file;
+    await this.storage.save(JSON.stringify(file));
+  }
+
+  async isInitialized(): Promise<boolean> {
+    return (await this.read()) !== undefined;
+  }
+
+  async initialize(password: string): Promise<void> {
+    if (await this.isInitialized()) {
+      throw new SecurityError("Vault is already initialized.");
+    }
+    const verifier = await this.crypto.encrypt(SENTINEL, password);
+    await this.write({ version: 1, verifier, credentials: {} });
+  }
+
+  async unlock(password: string): Promise<boolean> {
+    const file = await this.read();
+    if (!file) throw new SecurityError("Vault is not initialized.");
+    try {
+      const value = await this.crypto.decrypt(file.verifier, password);
+      return value === SENTINEL;
+    } catch {
+      return false;
+    }
+  }
+
+  private async requireUnlocked(password: string): Promise<VaultFile> {
+    const file = await this.read();
+    if (!file) throw new SecurityError("Vault is not initialized.");
+    if (!(await this.unlock(password))) {
+      throw new SecurityError("Incorrect vault password.");
+    }
+    return file;
+  }
+
+  async setCredential(password: string, providerId: string, secret: string): Promise<void> {
+    const file = await this.requireUnlocked(password);
+    const sealed = await this.crypto.encrypt(secret, password);
+    await this.write({
+      ...file,
+      credentials: { ...file.credentials, [providerId]: sealed },
+    });
+  }
+
+  async getCredential(password: string, providerId: string): Promise<string | undefined> {
+    const file = await this.requireUnlocked(password);
+    const sealed = file.credentials[providerId];
+    if (!sealed) return undefined;
+    return this.crypto.decrypt(sealed, password);
+  }
+
+  async listProviders(): Promise<readonly string[]> {
+    const file = await this.read();
+    return file ? Object.keys(file.credentials) : [];
+  }
+
+  async removeCredential(password: string, providerId: string): Promise<void> {
+    const file = await this.requireUnlocked(password);
+    const next = { ...file.credentials };
+    delete next[providerId];
+    await this.write({ ...file, credentials: next });
+  }
+
+  /**
+   * Wipe the whole vault — every stored credential and the password verifier.
+   * Used by a "forgot password" reset: the user loses all saved keys and then
+   * creates a fresh password. No password is required (the point is recovery
+   * when the password is lost).
+   */
+  async reset(): Promise<void> {
+    this.file = undefined;
+    await this.storage.clear();
+  }
+}

package/src/security/file-vault-storage.ts

@@ -0,0 +1,25 @@
+import { readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import type { VaultStorage } from "./credential-vault";
+
+/** Node file-backed vault storage (CLI + MCP). */
+export class FileVaultStorage implements VaultStorage {
+  constructor(private readonly filePath: string) {}
+
+  async load(): Promise<string | null> {
+    if (!existsSync(this.filePath)) return null;
+    const raw = await readFile(this.filePath, "utf8");
+    return raw.trim() ? raw : null;
+  }
+
+  async save(serialized: string): Promise<void> {
+    const dir = path.dirname(this.filePath);
+    if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+    await writeFile(this.filePath, serialized, { encoding: "utf8", mode: 0o600 });
+  }
+
+  async clear(): Promise<void> {
+    if (existsSync(this.filePath)) await rm(this.filePath, { force: true });
+  }
+}

package/src/security/index.ts

@@ -0,0 +1,8 @@
+export { EncryptedCredentialVault } from "./credential-vault";
+export type { VaultStorage } from "./credential-vault";
+export { SessionPasswordGate } from "./password-gate";
+export type { PasswordPrompt, SessionPasswordGateOptions } from "./password-gate";
+export { FileVaultStorage } from "./file-vault-storage";
+export { WebStorageVaultStorage } from "./web-storage-vault-storage";
+export { migratePlaintextKey } from "./migrate-plaintext-key";
+export type { PlaintextMigrationInput, PlaintextMigrationResult } from "./migrate-plaintext-key";

package/src/security/migrate-plaintext-key.ts

@@ -0,0 +1,38 @@
+import type { CredentialVault } from "../ports/security";
+
+export interface PlaintextMigrationInput {
+  readonly vault: CredentialVault;
+  readonly password: string;
+  /** Catalog provider id the key belongs to (e.g. "anthropic"). */
+  readonly providerId: string;
+  /** The legacy plaintext secret to import. */
+  readonly plaintextKey: string;
+  /** Clears the legacy plaintext store once the key is sealed. */
+  readonly clearPlaintext: () => void | Promise<void>;
+}
+
+export interface PlaintextMigrationResult {
+  readonly migrated: boolean;
+  readonly initializedVault: boolean;
+}
+
+/**
+ * Move a legacy plaintext API key into the encrypted vault, then wipe the
+ * plaintext source. Initializes the vault on first run. Idempotent: a blank key
+ * is a no-op.
+ */
+export async function migratePlaintextKey(
+  input: PlaintextMigrationInput,
+): Promise<PlaintextMigrationResult> {
+  if (!input.plaintextKey) {
+    return { migrated: false, initializedVault: false };
+  }
+  let initializedVault = false;
+  if (!(await input.vault.isInitialized())) {
+    await input.vault.initialize(input.password);
+    initializedVault = true;
+  }
+  await input.vault.setCredential(input.password, input.providerId, input.plaintextKey);
+  await input.clearPlaintext();
+  return { migrated: true, initializedVault };
+}

package/src/security/password-gate.ts

@@ -0,0 +1,62 @@
+import type { CredentialVault, PasswordGate, SensitiveOperation } from "../ports/security";
+import { SecurityError } from "../errors/app-error";
+
+/** Prompts the host environment for a password (CLI prompt, browser modal, …). */
+export type PasswordPrompt = (context: {
+  operation: SensitiveOperation;
+  firstRun: boolean;
+  attempt: number;
+}) => Promise<string>;
+
+export interface SessionPasswordGateOptions {
+  readonly vault: CredentialVault;
+  readonly prompt: PasswordPrompt;
+  /** Max password attempts before authorize() throws. Default 3. */
+  readonly maxAttempts?: number;
+  /** Cache the verified password for the process lifetime. Default true. */
+  readonly cacheForSession?: boolean;
+}
+
+/**
+ * Authorizes sensitive operations behind the local password. On first run it
+ * initializes the vault; subsequent calls verify (one unlock-per-session by
+ * default). Returns the verified password so callers can read the vault.
+ */
+export class SessionPasswordGate implements PasswordGate {
+  private cached?: string;
+
+  constructor(private readonly options: SessionPasswordGateOptions) {}
+
+  async authorize(operation: SensitiveOperation): Promise<string> {
+    if (this.options.cacheForSession !== false && this.cached) {
+      return this.cached;
+    }
+
+    const firstRun = !(await this.options.vault.isInitialized());
+    const maxAttempts = this.options.maxAttempts ?? 3;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      const password = await this.options.prompt({ operation, firstRun, attempt });
+
+      if (firstRun) {
+        await this.options.vault.initialize(password);
+        return this.remember(password);
+      }
+      if (await this.options.vault.unlock(password)) {
+        return this.remember(password);
+      }
+    }
+
+    throw new SecurityError(`Authorization failed for "${operation}" after ${maxAttempts} attempts.`);
+  }
+
+  private remember(password: string): string {
+    if (this.options.cacheForSession !== false) this.cached = password;
+    return password;
+  }
+
+  /** Clears any cached password (e.g. on logout). */
+  reset(): void {
+    this.cached = undefined;
+  }
+}