@hasna/knowledge 0.2.26 → 0.2.28

package/src/storage-contract.ts

@@ -1,293 +0,0 @@
-import { createHash, randomUUID } from 'node:crypto';
-import type { Database } from 'bun:sqlite';
-import { DEFAULT_KNOWLEDGE_API_URL, normalizeKnowledgeApiOrigin } from './auth';
-import { REMOTE_KNOWLEDGE_CONTRACT_VERSION } from './remote-client';
-import type { KnowledgeConfig, KnowledgeWorkspace } from './workspace';
-import { HASNA_KNOWLEDGE_APP_PATH } from './workspace';
-
-export interface StorageArtifactClass {
-  kind: string;
-  prefix: string;
-  description: string;
-}
-
-export interface StorageContract {
-  scope: string;
-  mode: KnowledgeConfig['mode'];
-  storage_type: KnowledgeConfig['storage']['type'];
-  workspace_home: string;
-  local_layout: {
-    app_path: string;
-    config_path: string;
-    json_store_path: string;
-    knowledge_db_path: string;
-    directories: Record<string, string>;
-  };
-  artifact_store: {
-    type: KnowledgeConfig['storage']['type'];
-    artifacts_root: string;
-    uri_prefix: string;
-    s3: {
-      bucket: string;
-      prefix: string;
-      region: string | null;
-      profile: string | null;
-      server_side_encryption: string | null;
-      kms_key_configured: boolean;
-    } | null;
-  };
-  hosted: {
-    enabled: boolean;
-    api_url: string;
-    api_url_env: 'KNOWLEDGE_API_URL';
-    api_key_env: 'KNOWLEDGE_API_KEY';
-    auth_storage: '~/.hasna/knowledge/auth.json';
-    remote_contract_version: typeof REMOTE_KNOWLEDGE_CONTRACT_VERSION;
-    requires_hosted_account_for_local_use: false;
-  };
-  source_ownership: {
-    owner: 'open-files';
-    preferred_ref: string;
-    allowed_schemes: string[];
-    raw_source_bytes_stored_in_open_knowledge: false;
-    stores: string[];
-    does_not_store: string[];
-  };
-  generated_artifacts: StorageArtifactClass[];
-  scalability: {
-    catalog: string;
-    indexes: string;
-    logs: string;
-    markdown: string;
-  };
-  warnings: string[];
-}
-
-export interface StorageValidationResult {
-  ok: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
-export interface GeneratedStorageObject {
-  uri: string;
-  key: string;
-  kind: string;
-  content_type?: string;
-  hash?: string;
-  size_bytes?: number;
-  metadata?: Record<string, unknown>;
-}
-
-const GENERATED_ARTIFACTS: StorageArtifactClass[] = [
-  {
-    kind: 'schema',
-    prefix: 'schemas/',
-    description: 'Machine-readable agent schemas and source rules.',
-  },
-  {
-    kind: 'index',
-    prefix: 'indexes/',
-    description: 'Small orientation indexes and future shard manifests.',
-  },
-  {
-    kind: 'log',
-    prefix: 'logs/',
-    description: 'Append-only JSONL run and wiki-maintenance log partitions.',
-  },
-  {
-    kind: 'run',
-    prefix: 'runs/',
-    description: 'Prompt/tool/cost ledgers and generated output records.',
-  },
-  {
-    kind: 'wiki_page',
-    prefix: 'wiki/',
-    description: 'Generated cited Markdown pages, not raw source files.',
-  },
-  {
-    kind: 'export',
-    prefix: 'exports/',
-    description: 'Portable exports and snapshots of derived knowledge state.',
-  },
-];
-
-export function hashArtifactBody(body: string | Uint8Array): { hash: string; size_bytes: number } {
-  const bytes = typeof body === 'string' ? Buffer.from(body) : Buffer.from(body);
-  return {
-    hash: `sha256:${createHash('sha256').update(bytes).digest('hex')}`,
-    size_bytes: bytes.byteLength,
-  };
-}
-
-export function artifactKindForKey(key: string): string {
-  const match = GENERATED_ARTIFACTS.find((entry) => key.startsWith(entry.prefix));
-  return match?.kind ?? 'artifact';
-}
-
-export function resolveStorageContract(
-  config: KnowledgeConfig,
-  workspace: KnowledgeWorkspace,
-  scope = 'global',
-): StorageContract {
-  const validation = validateStorageConfig(config, workspace);
-  const s3 = config.storage.s3 ?? null;
-  const prefix = s3?.prefix?.replace(/^\/+|\/+$/g, '') ?? '';
-  const s3UriPrefix = s3 ? `s3://${s3.bucket}/${prefix ? `${prefix}/` : ''}` : '';
-
-  return {
-    scope,
-    mode: config.mode,
-    storage_type: config.storage.type,
-    workspace_home: workspace.home,
-    local_layout: {
-      app_path: HASNA_KNOWLEDGE_APP_PATH,
-      config_path: workspace.configPath,
-      json_store_path: workspace.jsonStorePath,
-      knowledge_db_path: workspace.knowledgeDbPath,
-      directories: {
-        artifacts: workspace.artifactsDir,
-        cache: workspace.cacheDir,
-        exports: workspace.exportsDir,
-        indexes: workspace.indexesDir,
-        logs: workspace.logsDir,
-        runs: workspace.runsDir,
-        schemas: workspace.schemasDir,
-        wiki: workspace.wikiDir,
-      },
-    },
-    artifact_store: {
-      type: config.storage.type,
-      artifacts_root: config.storage.artifacts_root,
-      uri_prefix: config.storage.type === 's3' ? s3UriPrefix : `file://${workspace.artifactsDir}/`,
-      s3: s3
-        ? {
-            bucket: s3.bucket,
-            prefix,
-            region: s3.region ?? null,
-            profile: s3.profile ?? null,
-            server_side_encryption: s3.server_side_encryption ?? null,
-            kms_key_configured: Boolean(s3.kms_key_id),
-          }
-        : null,
-    },
-    hosted: {
-      enabled: config.mode === 'hosted',
-      api_url: normalizeKnowledgeApiOrigin(config.hosted?.api_url ?? DEFAULT_KNOWLEDGE_API_URL),
-      api_url_env: 'KNOWLEDGE_API_URL',
-      api_key_env: 'KNOWLEDGE_API_KEY',
-      auth_storage: '~/.hasna/knowledge/auth.json',
-      remote_contract_version: REMOTE_KNOWLEDGE_CONTRACT_VERSION,
-      requires_hosted_account_for_local_use: false,
-    },
-    source_ownership: {
-      owner: 'open-files',
-      preferred_ref: config.sources.preferred_ref,
-      allowed_schemes: config.sources.allowed_schemes,
-      raw_source_bytes_stored_in_open_knowledge: false,
-      stores: [
-        'source refs',
-        'source revisions and hashes',
-        'citation spans',
-        'redacted extracted chunks',
-        'embeddings',
-        'generated wiki artifacts',
-        'indexes',
-        'run ledgers',
-      ],
-      does_not_store: [
-        'raw open-files bytes',
-        'S3 object credentials',
-        'connector secrets',
-        'hosted tenant ownership state',
-      ],
-    },
-    generated_artifacts: GENERATED_ARTIFACTS,
-    scalability: {
-      catalog: 'knowledge.db tracks sources, revisions, chunks, citations, indexes, runs, and storage_objects.',
-      indexes: 'Indexes are cataloged DB rows plus sharded artifacts, not one giant index.md.',
-      logs: 'Logs use dated JSONL partitions under logs/yyyy/mm/dd.jsonl.',
-      markdown: 'Markdown pages are the readable wiki layer over DB/object-store state.',
-    },
-    warnings: validation.warnings,
-  };
-}
-
-export function validateStorageConfig(config: KnowledgeConfig, workspace: KnowledgeWorkspace): StorageValidationResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  if (!workspace.home.endsWith(HASNA_KNOWLEDGE_APP_PATH)) {
-    warnings.push(`Workspace home does not end with ${HASNA_KNOWLEDGE_APP_PATH}: ${workspace.home}`);
-  }
-
-  if (config.storage.type === 's3') {
-    if (!config.storage.s3?.bucket) errors.push('storage.s3.bucket is required when storage.type is s3.');
-    if (!config.storage.s3?.prefix) warnings.push('storage.s3.prefix is empty; generated knowledge artifacts will be written at the bucket root.');
-    if (config.mode === 'local') warnings.push('storage.type is s3 while mode is local; this is valid for BYO S3, but hosted wrappers should set mode to hosted.');
-  }
-
-  if (config.storage.type === 'local' && config.storage.s3) {
-    warnings.push('storage.s3 is configured but ignored while storage.type is local.');
-  }
-
-  if (config.sources.preferred_ref !== 'open-files') {
-    warnings.push('sources.preferred_ref should stay open-files for durable company knowledge.');
-  }
-
-  if (!config.sources.allowed_schemes.includes('open-files')) {
-    errors.push('sources.allowed_schemes must include open-files.');
-  }
-
-  if (config.mode === 'hosted' && config.hosted?.api_url) {
-    try {
-      normalizeKnowledgeApiOrigin(config.hosted.api_url);
-    } catch {
-      errors.push('hosted.api_url must be an http(s) URL when mode is hosted.');
-    }
-  }
-
-  return {
-    ok: errors.length === 0,
-    errors,
-    warnings,
-  };
-}
-
-export function recordStorageObjects(db: Database, objects: GeneratedStorageObject[], now = new Date()): void {
-  const timestamp = now.toISOString();
-  const statement = db.prepare(`
-    INSERT INTO storage_objects (
-      id, artifact_uri, kind, content_type, hash, size_bytes, metadata_json, created_at, updated_at
-    )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(artifact_uri) DO UPDATE SET
-      kind = excluded.kind,
-      content_type = excluded.content_type,
-      hash = excluded.hash,
-      size_bytes = excluded.size_bytes,
-      metadata_json = excluded.metadata_json,
-      updated_at = excluded.updated_at
-  `);
-
-  const insert = db.transaction((entries: GeneratedStorageObject[]) => {
-    for (const entry of entries) {
-      statement.run(
-        randomUUID(),
-        entry.uri,
-        entry.kind,
-        entry.content_type ?? null,
-        entry.hash ?? null,
-        entry.size_bytes ?? null,
-        JSON.stringify({
-          key: entry.key,
-          ...(entry.metadata ?? {}),
-        }),
-        timestamp,
-        timestamp,
-      );
-    }
-  });
-
-  insert(objects);
-}

package/src/store.ts

@@ -1,113 +0,0 @@
-/**
- * @hasna/knowledge
- * Copyright 2026 Hasna Inc.
- * Licensed under the Apache License, Version 2.0
- */
-import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
-import { ensureParentDir, globalKnowledgeHome, legacyGlobalStorePath, workspaceForHome } from './workspace';
-
-export interface KnowledgeItem {
-  id: string;
-  short_id?: string | null;
-  title: string;
-  content: string;
-  url: string | null;
-  tags: string[];
-  metadata?: Record<string, unknown>;
-  archived?: boolean;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface Store {
-  items: KnowledgeItem[];
-}
-
-export function defaultStorePath(): string {
-  return workspaceForHome(globalKnowledgeHome()).jsonStorePath;
-}
-
-export function ensureStore(path: string): void {
-  if (!existsSync(path)) {
-    ensureParentDir(path);
-    if (path === defaultStorePath() && existsSync(legacyGlobalStorePath())) {
-      writeFileSync(path, readFileSync(legacyGlobalStorePath(), 'utf8'));
-    } else {
-      writeFileSync(path, JSON.stringify({ items: [] }, null, 2));
-    }
-  }
-}
-
-function lockPath(path: string): string {
-  return `${path}.lock`;
-}
-
-function acquireLock(lockPath: string, ownerId: string): void {
-  const maxWait = 5000;
-  const interval = 50;
-  const start = Date.now();
-  while (Date.now() - start < maxWait) {
-    try {
-      if (!existsSync(lockPath)) {
-        writeFileSync(lockPath, JSON.stringify({ owner: ownerId, ts: Date.now() }));
-        return;
-      }
-      const lock = JSON.parse(readFileSync(lockPath, 'utf8')) as { owner: string; ts: number };
-      if (Date.now() - lock.ts > 10000) {
-        unlinkSync(lockPath);
-      }
-    } catch {
-      // lock file disappeared, try again
-    }
-    const start2 = Date.now();
-    while (Date.now() - start2 < interval) {}
-  }
-  throw new Error(`Could not acquire lock on ${lockPath} after ${maxWait}ms`);
-}
-
-function releaseLock(lockPath: string, ownerId: string): void {
-  try {
-    if (existsSync(lockPath)) {
-      const lock = JSON.parse(readFileSync(lockPath, 'utf8')) as { owner: string; ts: number };
-      if (lock.owner === ownerId) {
-        unlinkSync(lockPath);
-      }
-    }
-  } catch {}
-}
-
-export function loadStore(path: string): Store {
-  ensureStore(path);
-  const raw = readFileSync(path, 'utf8');
-  const parsed = JSON.parse(raw) as Store;
-  if (!parsed || !Array.isArray(parsed.items)) {
-    return { items: [] };
-  }
-  return parsed;
-}
-
-export function saveStore(path: string, store: Store): void {
-  const tmp = `${path}.tmp.${randomUUID()}`;
-  writeFileSync(tmp, JSON.stringify(store, null, 2));
-  renameSync(tmp, path);
-}
-
-export function withLock<T>(path: string, fn: () => T): T {
-  const owner = randomUUID();
-  const lpath = lockPath(path);
-  acquireLock(lpath, owner);
-  try {
-    return fn();
-  } finally {
-    releaseLock(lpath, owner);
-  }
-}
-
-export function makeId(): string {
-  return `k_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-}
-
-export function makeShortId(id: string): string {
-  return id.replace(/^k_/, '').slice(0, 12);
-}