@hasna/knowledge 0.2.3 → 0.2.5

package/src/store.ts

@@ -3,17 +3,19 @@
  * Copyright 2026 Hasna Inc.
  * Licensed under the Apache License, Version 2.0
  */
-import { mkdirSync, readFileSync, writeFileSync, existsSync, renameSync, unlinkSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { homedir } from 'node:os';
+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;
 }
@@ -23,13 +25,17 @@ export interface Store {
 }
 
 export function defaultStorePath(): string {
-  return `${homedir()}/.open-knowledge/db.json`;
+  return workspaceForHome(globalKnowledgeHome()).jsonStorePath;
 }
 
 export function ensureStore(path: string): void {
   if (!existsSync(path)) {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify({ items: [] }, null, 2));
+    ensureParentDir(path);
+    if (path === defaultStorePath() && existsSync(legacyGlobalStorePath())) {
+      writeFileSync(path, readFileSync(legacyGlobalStorePath(), 'utf8'));
+    } else {
+      writeFileSync(path, JSON.stringify({ items: [] }, null, 2));
+    }
   }
 }
 
@@ -101,3 +107,7 @@ export function withLock<T>(path: string, fn: () => T): T {
 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);
+}

package/src/wiki-layout.ts

@@ -0,0 +1,104 @@
+import type { ArtifactStore } from './artifact-store';
+
+export interface WikiLayoutInitResult {
+  schema_key: string;
+  root_index_key: string;
+  wiki_readme_key: string;
+  log_key: string;
+  written: string[];
+}
+
+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 };
+}
+
+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 writes = [
+    store.put({ key: schemaKey, body: agentSchemaTemplate(), content_type: 'text/markdown' }),
+    store.put({ key: rootIndexKey, body: rootIndexTemplate(), content_type: 'text/markdown' }),
+    store.put({ key: wikiReadmeKey, body: wikiReadmeTemplate(), content_type: 'text/markdown' }),
+    store.put({ key: logKey, body: `${JSON.stringify(event)}\n`, content_type: 'application/x-ndjson' }),
+  ];
+
+  await Promise.all(writes);
+  return {
+    schema_key: schemaKey,
+    root_index_key: rootIndexKey,
+    wiki_readme_key: wikiReadmeKey,
+    log_key: logKey,
+    written: [schemaKey, rootIndexKey, wikiReadmeKey, logKey],
+  };
+}

package/src/workspace.ts

@@ -0,0 +1,123 @@
+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';
+  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[];
+  };
+}
+
+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',
+    storage: {
+      type: 'local',
+      artifacts_root: 'artifacts',
+    },
+    sources: {
+      preferred_ref: 'open-files',
+      allowed_schemes: ['open-files', 's3', 'file', 'https', 'http'],
+    },
+  };
+}
+
+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;
+}