@hasna/knowledge 0.2.27 → 0.2.28

package/src/wiki-layout.ts

@@ -1,251 +0,0 @@
-import { createHash } from 'node:crypto';
-import type { Database } from 'bun:sqlite';
-import type { ArtifactStore } from './artifact-store';
-import { generatedArtifactProvenance, type GeneratedArtifactProvenance } from './provenance';
-import {
-  artifactKindForKey,
-  hashArtifactBody,
-  type GeneratedStorageObject,
-} from './storage-contract';
-
-export interface WikiLayoutInitResult {
-  schema_key: string;
-  root_index_key: string;
-  wiki_readme_key: string;
-  log_key: string;
-  artifacts: GeneratedStorageObject[];
-  written: string[];
-}
-
-interface CatalogArtifact {
-  key: string;
-  uri: string;
-  hash?: string;
-  metadata?: Record<string, unknown>;
-}
-
-function todayParts(now: Date): { year: string; month: string; day: string } {
-  const year = String(now.getUTCFullYear());
-  const month = String(now.getUTCMonth() + 1).padStart(2, '0');
-  const day = String(now.getUTCDate()).padStart(2, '0');
-  return { year, month, day };
-}
-
-function stableId(prefix: string, value: string): string {
-  return `${prefix}_${createHash('sha256').update(value).digest('hex').slice(0, 20)}`;
-}
-
-function estimateTokenCount(text: string): number {
-  const words = text.trim().split(/\s+/).filter(Boolean).length;
-  return Math.max(1, Math.ceil(words * 1.25));
-}
-
-export function agentSchemaTemplate(): string {
-  return `# Knowledge Agent Schema v1
-
-## Source Rules
-
-- Treat open-files source references as the preferred source of truth.
-- Do not copy raw source files into open-knowledge.
-- Cite every durable fact with a source URI, revision/hash when available, and optional span.
-- Mark uncertainty explicitly when sources disagree or are incomplete.
-
-## Wiki Rules
-
-- Write generated knowledge as Markdown pages under wiki/.
-- Keep root indexes small; use topic, team, project, and machine-readable shards for scale.
-- Preserve backlinks between related pages and decisions.
-- Prefer updating existing pages over creating near-duplicates.
-
-## Query Rules
-
-- Search wiki pages first, then source chunks, then deeper read-only source refs.
-- Use web search only when requested or when current external context is required.
-- File useful answers back into the wiki only after approval or approved auto-write mode.
-
-## Lint Rules
-
-- Flag stale pages, missing citations, contradictions, orphan pages, duplicate pages, and unresolved source refs.
-`;
-}
-
-export function rootIndexTemplate(): string {
-  return `# Knowledge Index
-
-This is a compact orientation index for agents. It is not the full search index.
-
-## Shards
-
-- wiki/
-- indexes/
-- schemas/
-- logs/
-
-## Source Ownership
-
-Raw source files are resolved through open-files. This app stores source refs,
-citations, chunks, generated wiki artifacts, indexes, and run records.
-`;
-}
-
-export function wikiReadmeTemplate(): string {
-  return `# Wiki
-
-Generated durable knowledge pages live here.
-
-Pages should be concise, cited, and organized for both humans and agents.
-`;
-}
-
-export async function initializeWikiLayout(store: ArtifactStore, now = new Date()): Promise<WikiLayoutInitResult> {
-  const { year, month, day } = todayParts(now);
-  const schemaKey = 'schemas/v1.md';
-  const rootIndexKey = 'indexes/root.md';
-  const wikiReadmeKey = 'wiki/README.md';
-  const logKey = `logs/${year}/${month}/${day}.jsonl`;
-  const event = {
-    ts: now.toISOString(),
-    event: 'wiki_layout_initialized',
-    schema_key: schemaKey,
-    root_index_key: rootIndexKey,
-    wiki_readme_key: wikiReadmeKey,
-  };
-
-  const entries = [
-    { key: schemaKey, body: agentSchemaTemplate(), content_type: 'text/markdown' },
-    { key: rootIndexKey, body: rootIndexTemplate(), content_type: 'text/markdown' },
-    { key: wikiReadmeKey, body: wikiReadmeTemplate(), content_type: 'text/markdown' },
-    { key: logKey, body: `${JSON.stringify(event)}\n`, content_type: 'application/x-ndjson' },
-  ];
-
-  const artifacts = await Promise.all(entries.map(async (entry) => {
-    const result = await store.put(entry);
-    return {
-      key: result.key,
-      uri: result.uri,
-      kind: artifactKindForKey(entry.key),
-      content_type: entry.content_type,
-      metadata: {
-        provenance: generatedArtifactProvenance({
-          generated_from: 'wiki_layout_init',
-          artifact_key: entry.key,
-          citation_required: entry.key.startsWith('wiki/') || entry.key.startsWith('indexes/'),
-        }),
-      },
-      ...hashArtifactBody(entry.body),
-    };
-  }));
-  return {
-    schema_key: schemaKey,
-    root_index_key: rootIndexKey,
-    wiki_readme_key: wikiReadmeKey,
-    log_key: logKey,
-    artifacts,
-    written: [schemaKey, rootIndexKey, wikiReadmeKey, logKey],
-  };
-}
-
-function provenanceFor(artifact: CatalogArtifact): GeneratedArtifactProvenance {
-  const existing = artifact.metadata?.provenance;
-  if (existing && typeof existing === 'object' && !Array.isArray(existing)) {
-    return existing as GeneratedArtifactProvenance;
-  }
-  return generatedArtifactProvenance({
-    generated_from: 'wiki_layout_init',
-    artifact_key: artifact.key,
-  });
-}
-
-function recordWikiChunk(db: Database, pageId: string, title: string, artifact: CatalogArtifact, body: string, now: string): void {
-  const provenance = provenanceFor(artifact);
-  const chunkId = stableId('chk', `${pageId}\u0000${artifact.hash ?? artifact.uri}`);
-  const existing = db.query<{ id: string }, [string]>('SELECT id FROM chunks WHERE wiki_page_id = ?').all(pageId);
-  for (const row of existing) db.run('DELETE FROM chunks_fts WHERE chunk_id = ?', [row.id]);
-  db.run('DELETE FROM chunks WHERE wiki_page_id = ?', [pageId]);
-  db.run(
-    `INSERT INTO chunks (id, wiki_page_id, kind, ordinal, text, token_count, start_offset, end_offset, metadata_json, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    [
-      chunkId,
-      pageId,
-      'wiki',
-      0,
-      body,
-      estimateTokenCount(body),
-      0,
-      body.length,
-      JSON.stringify({
-        artifact_key: artifact.key,
-        artifact_uri: artifact.uri,
-        content_hash: artifact.hash ?? null,
-        provenance,
-      }),
-      now,
-    ],
-  );
-  db.run(
-    'INSERT INTO chunks_fts (chunk_id, text, title, source_uri) VALUES (?, ?, ?, ?)',
-    [chunkId, body, title, artifact.uri],
-  );
-}
-
-export function recordWikiLayoutCatalog(db: Database, artifacts: CatalogArtifact[], now = new Date()): void {
-  const timestamp = now.toISOString();
-  const rootIndex = artifacts.find((artifact) => artifact.key.endsWith('indexes/root.md'));
-  const wikiReadme = artifacts.find((artifact) => artifact.key.endsWith('wiki/README.md'));
-
-  if (rootIndex) {
-    db.run(
-      `INSERT INTO knowledge_indexes (id, kind, name, artifact_uri, shard_key, metadata_json, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(kind, name, shard_key) DO UPDATE SET
-         artifact_uri = excluded.artifact_uri,
-         metadata_json = excluded.metadata_json,
-         updated_at = excluded.updated_at`,
-      [
-        stableId('idx', 'root:indexes/root.md'),
-        'root',
-        'root',
-        rootIndex.uri,
-        'root',
-        JSON.stringify({
-          artifact_key: rootIndex.key,
-          content_hash: rootIndex.hash ?? null,
-          provenance: provenanceFor(rootIndex),
-        }),
-        timestamp,
-        timestamp,
-      ],
-    );
-  }
-
-  if (wikiReadme) {
-    const wikiPageId = stableId('wiki', 'wiki/README.md');
-    db.run(
-      `INSERT INTO wiki_pages (id, path, title, artifact_uri, content_hash, status, metadata_json, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(path) DO UPDATE SET
-         title = excluded.title,
-         artifact_uri = excluded.artifact_uri,
-         content_hash = excluded.content_hash,
-         status = excluded.status,
-         metadata_json = excluded.metadata_json,
-         updated_at = excluded.updated_at`,
-      [
-        wikiPageId,
-        'wiki/README.md',
-        'Wiki',
-        wikiReadme.uri,
-        wikiReadme.hash ?? null,
-        'active',
-        JSON.stringify({
-          artifact_key: wikiReadme.key,
-          provenance: provenanceFor(wikiReadme),
-        }),
-        timestamp,
-        timestamp,
-      ],
-    );
-    recordWikiChunk(db, wikiPageId, 'Wiki', wikiReadme, wikiReadmeTemplate(), timestamp);
-  }
-}

package/src/workspace.ts

@@ -1,251 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-
-export const HASNA_KNOWLEDGE_APP_PATH = join('.hasna', 'apps', 'knowledge');
-
-export interface KnowledgeWorkspace {
-  home: string;
-  configPath: string;
-  jsonStorePath: string;
-  knowledgeDbPath: string;
-  artifactsDir: string;
-  cacheDir: string;
-  exportsDir: string;
-  indexesDir: string;
-  logsDir: string;
-  runsDir: string;
-  schemasDir: string;
-  wikiDir: string;
-}
-
-export interface KnowledgeConfig {
-  version: 1;
-  mode: 'local' | 'hosted';
-  hosted?: {
-    api_url?: string;
-  };
-  storage: {
-    type: 'local' | 's3';
-    artifacts_root: string;
-    s3?: {
-      bucket: string;
-      prefix?: string;
-      region?: string;
-      profile?: string;
-      max_attempts?: number;
-      server_side_encryption?: 'AES256' | 'aws:kms';
-      kms_key_id?: string;
-    };
-  };
-  sources: {
-    preferred_ref: 'open-files';
-    allowed_schemes: string[];
-  };
-  embeddings?: {
-    default_model?: string;
-    dimensions?: number;
-    batch_size?: number;
-    max_parallel_calls?: number;
-  };
-  providers?: {
-    default_model?: string;
-    aliases?: Record<string, string>;
-    openai?: {
-      api_key_env?: string;
-      base_url?: string;
-      default_model?: string;
-    };
-    anthropic?: {
-      api_key_env?: string;
-      base_url?: string;
-      default_model?: string;
-    };
-    deepseek?: {
-      api_key_env?: string;
-      base_url?: string;
-      default_model?: string;
-    };
-  };
-  safety?: {
-    network?: {
-      web_search_enabled?: boolean;
-      s3_reads_enabled?: boolean;
-      allowed_s3_buckets?: string[];
-    };
-    redaction?: {
-      enabled?: boolean;
-    };
-    approvals?: {
-      generated_writes_require_approval?: boolean;
-    };
-  };
-}
-
-export const HASNA_XYZ_KNOWLEDGE_CANONICAL = {
-  division: 'xyz',
-  app_type: 'opensource',
-  app: 'knowledge',
-  env: 'prod',
-  local_path: HASNA_KNOWLEDGE_APP_PATH,
-  s3: {
-    bucket: 'hasna-xyz-opensource-knowledge-prod',
-    region: 'us-east-1',
-    profile: 'hasna-xyz-infra',
-    prefix: '.hasna/apps/knowledge',
-    server_side_encryption: 'AES256',
-  },
-  secrets: {
-    env: 'hasna/xyz/opensource/knowledge/prod/env',
-    aws: 'hasna/xyz/opensource/knowledge/prod/aws',
-    s3: 'hasna/xyz/opensource/knowledge/prod/s3',
-    rds: null,
-    future_rds: 'hasna/xyz/opensource/knowledge/prod/rds',
-  },
-  source_owner: 'open-files',
-  evidence_doc: 'docs/canonical-secrets-bootstrap-2026-06-08.md',
-} as const;
-
-export function canonicalHasnaXyzKnowledgeStorage(): KnowledgeConfig['storage'] {
-  return {
-    type: 's3',
-    artifacts_root: 'artifacts',
-    s3: {
-      bucket: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.bucket,
-      prefix: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.prefix,
-      region: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.region,
-      profile: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.profile,
-      server_side_encryption: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.server_side_encryption,
-    },
-  };
-}
-
-export function legacyGlobalStorePath(): string {
-  return join(homedir(), '.open-knowledge', 'db.json');
-}
-
-export function globalKnowledgeHome(): string {
-  return join(homedir(), '.hasna', 'apps', 'knowledge');
-}
-
-export function projectKnowledgeHome(cwd = process.cwd()): string {
-  return resolve(cwd, HASNA_KNOWLEDGE_APP_PATH);
-}
-
-export function workspaceForHome(home: string): KnowledgeWorkspace {
-  return {
-    home,
-    configPath: join(home, 'config.json'),
-    jsonStorePath: join(home, 'db.json'),
-    knowledgeDbPath: join(home, 'knowledge.db'),
-    artifactsDir: join(home, 'artifacts'),
-    cacheDir: join(home, 'cache'),
-    exportsDir: join(home, 'exports'),
-    indexesDir: join(home, 'indexes'),
-    logsDir: join(home, 'logs'),
-    runsDir: join(home, 'runs'),
-    schemasDir: join(home, 'schemas'),
-    wikiDir: join(home, 'wiki'),
-  };
-}
-
-export function defaultKnowledgeConfig(): KnowledgeConfig {
-  return {
-    version: 1,
-    mode: 'local',
-    hosted: {
-      api_url: 'https://knowledge.hasna.xyz',
-    },
-    storage: {
-      type: 'local',
-      artifacts_root: 'artifacts',
-    },
-    sources: {
-      preferred_ref: 'open-files',
-      allowed_schemes: ['open-files', 's3', 'file', 'https', 'http'],
-    },
-    providers: {
-      default_model: 'openai:gpt-5.2',
-      aliases: {
-        fast: 'openai:gpt-5-mini',
-        reasoning: 'anthropic:claude-opus-4-6',
-        sonnet: 'anthropic:claude-sonnet-4-6',
-        deepseek: 'deepseek:deepseek-chat',
-        'deepseek-reasoning': 'deepseek:deepseek-reasoner',
-      },
-      openai: {
-        api_key_env: 'OPENAI_API_KEY',
-        default_model: 'gpt-5.2',
-      },
-      anthropic: {
-        api_key_env: 'ANTHROPIC_API_KEY',
-        default_model: 'claude-sonnet-4-6',
-      },
-      deepseek: {
-        api_key_env: 'DEEPSEEK_API_KEY',
-        default_model: 'deepseek-chat',
-      },
-    },
-    embeddings: {
-      default_model: 'openai:text-embedding-3-small',
-      dimensions: 1536,
-      batch_size: 64,
-      max_parallel_calls: 4,
-    },
-    safety: {
-      network: {
-        web_search_enabled: false,
-        s3_reads_enabled: false,
-        allowed_s3_buckets: [],
-      },
-      redaction: {
-        enabled: true,
-      },
-      approvals: {
-        generated_writes_require_approval: true,
-      },
-    },
-  };
-}
-
-export function ensureKnowledgeWorkspace(home: string): KnowledgeWorkspace {
-  const workspace = workspaceForHome(home);
-  mkdirSync(workspace.home, { recursive: true });
-  for (const dir of [
-    workspace.artifactsDir,
-    workspace.cacheDir,
-    workspace.exportsDir,
-    workspace.indexesDir,
-    workspace.logsDir,
-    workspace.runsDir,
-    workspace.schemasDir,
-    workspace.wikiDir,
-  ]) {
-    mkdirSync(dir, { recursive: true });
-  }
-  if (!existsSync(workspace.configPath)) {
-    writeFileSync(workspace.configPath, `${JSON.stringify(defaultKnowledgeConfig(), null, 2)}\n`);
-  }
-  return workspace;
-}
-
-export function resolveScopedWorkspace(scope: string | undefined, cwd = process.cwd()): KnowledgeWorkspace {
-  if (scope === 'project' || scope === 'local') {
-    return workspaceForHome(projectKnowledgeHome(cwd));
-  }
-  return workspaceForHome(globalKnowledgeHome());
-}
-
-export function ensureParentDir(path: string): void {
-  mkdirSync(dirname(path), { recursive: true });
-}
-
-export function readKnowledgeConfig(path: string): KnowledgeConfig {
-  const raw = readFileSync(path, 'utf8');
-  return JSON.parse(raw) as KnowledgeConfig;
-}
-
-export function writeKnowledgeConfig(path: string, config: KnowledgeConfig): void {
-  ensureParentDir(path);
-  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
-}