@hasna/knowledge 0.2.2 → 0.2.4

package/src/source-ref.ts

@@ -0,0 +1,92 @@
+export type SourceRefKind = 'open-files' | 's3' | 'file' | 'web';
+
+export interface BaseSourceRef {
+  kind: SourceRefKind;
+  uri: string;
+}
+
+export interface OpenFilesSourceRef extends BaseSourceRef {
+  kind: 'open-files';
+  entity: 'file' | 'source';
+  id: string;
+  revision_id?: string;
+  path?: string;
+}
+
+export interface S3SourceRef extends BaseSourceRef {
+  kind: 's3';
+  bucket: string;
+  key: string;
+}
+
+export interface FileSourceRef extends BaseSourceRef {
+  kind: 'file';
+  path: string;
+}
+
+export interface WebSourceRef extends BaseSourceRef {
+  kind: 'web';
+  url: string;
+}
+
+export type SourceRef = OpenFilesSourceRef | S3SourceRef | FileSourceRef | WebSourceRef;
+
+function assertNonEmpty(value: string | undefined, message: string): string {
+  if (!value) throw new Error(message);
+  return value;
+}
+
+function parseOpenFilesRef(uri: string): OpenFilesSourceRef {
+  const withoutScheme = uri.slice('open-files://'.length);
+  const parts = withoutScheme.split('/').filter(Boolean);
+  const entity = parts[0];
+  if (entity !== 'file' && entity !== 'source') {
+    throw new Error("Invalid open-files ref. Expected open-files://file/<id>, open-files://file/<id>/revision/<revision_id>, or open-files://source/<id>/path/<path>.");
+  }
+  const id = assertNonEmpty(parts[1], 'Invalid open-files ref. Missing id.');
+  if (entity === 'file') {
+    if (parts.length === 2) return { kind: 'open-files', uri, entity, id };
+    if (parts[2] === 'revision' && parts[3] && parts.length === 4) {
+      return { kind: 'open-files', uri, entity, id, revision_id: decodeURIComponent(parts[3]) };
+    }
+    throw new Error('Invalid open-files file ref. Expected open-files://file/<id>/revision/<revision_id>.');
+  }
+  const pathIndex = parts.indexOf('path');
+  const path = pathIndex >= 0 ? decodeURIComponent(parts.slice(pathIndex + 1).join('/')) : undefined;
+  return { kind: 'open-files', uri, entity, id, path };
+}
+
+function parseS3Ref(uri: string): S3SourceRef {
+  const parsed = new URL(uri);
+  const bucket = assertNonEmpty(parsed.hostname, 'Invalid s3 ref. Missing bucket.');
+  const key = decodeURIComponent(parsed.pathname.replace(/^\/+/, ''));
+  if (!key) throw new Error('Invalid s3 ref. Missing object key.');
+  return { kind: 's3', uri, bucket, key };
+}
+
+function parseFileRef(uri: string): FileSourceRef {
+  const parsed = new URL(uri);
+  return { kind: 'file', uri, path: decodeURIComponent(parsed.pathname) };
+}
+
+function parseWebRef(uri: string): WebSourceRef {
+  const parsed = new URL(uri);
+  return { kind: 'web', uri, url: parsed.toString() };
+}
+
+export function parseSourceRef(uri: string): SourceRef {
+  if (uri.startsWith('open-files://')) return parseOpenFilesRef(uri);
+  if (uri.startsWith('s3://')) return parseS3Ref(uri);
+  if (uri.startsWith('file://')) return parseFileRef(uri);
+  if (uri.startsWith('https://') || uri.startsWith('http://')) return parseWebRef(uri);
+  throw new Error(`Unsupported source ref scheme: ${uri}`);
+}
+
+export function isSupportedSourceRef(uri: string): boolean {
+  try {
+    parseSourceRef(uri);
+    return true;
+  } catch {
+    return false;
+  }
+}

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;
+}

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,59 +0,0 @@
-name: Bug Report
-description: Report a bug in open-knowledge
-labels: [bug]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for reporting a bug!
-  - type: textarea
-    id: description
-    attributes:
-      label: Bug Description
-      description: A clear description of the bug
-    validations:
-      required: true
-  - type: textarea
-    id: steps
-    attributes:
-      label: Steps to Reproduce
-      description: |
-        1.
-        2.
-        3.
-    validations:
-      required: true
-  - type: textarea
-    id: expected
-    attributes:
-      label: Expected Behavior
-    validations:
-      required: true
-  - type: textarea
-    id: actual
-    attributes:
-      label: Actual Behavior
-    validations:
-      required: true
-  - type: input
-    id: version
-    attributes:
-      label: Version
-      description: Output of `open-knowledge --version`
-  - type: dropdown
-    id: os
-    attributes:
-      label: Operating System
-      options:
-        - macOS
-        - Linux
-        - Windows
-        - Other
-  - type: dropdown
-    id: runtime
-    attributes:
-      label: Runtime
-      options:
-        - Bun
-        - Node.js
-        - Other

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,34 +0,0 @@
-name: Feature Request
-description: Suggest a new feature or improvement
-labels: [enhancement]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Ideas are welcome! The best features solve real problems for AI agents and CLI users.
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem or Motivation
-      description: What problem does this solve?
-    validations:
-      required: true
-  - type: textarea
-    id: solution
-    attributes:
-      label: Proposed Solution
-      description: How would you like it to work?
-    validations:
-      required: true
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives Considered
-      description: Any other approaches you considered?
-  - type: checkboxes
-    id: willingness
-    attributes:
-      label: Willingness to Implement
-      options:
-        - label: I am willing to implement this feature
-        - label: I can help test a PR for this feature

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,21 +0,0 @@
-## Summary
-
-<!-- 1-3 sentence description of the change -->
-
-## Motivation
-
-<!-- Why is this change needed? What problem does it solve? -->
-
-## Changes
-
-<!-- Bulleted list of what was changed -->
-
-## Testing
-
-<!-- How was this tested? -->
-
-## Checklist
-
-- [ ] Tests added / updated
-- [ ] Documentation updated (if needed)
-- [ ] `bun test` passes

package/.github/workflows/ci.yml

@@ -1,49 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-        runtime: [bun, node]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Bun
-        if: matrix.runtime == 'bun'
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Setup Node
-        if: matrix.runtime == 'node'
-        uses: actions/setup-node@v4
-        with:
-          node-version: latest
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Run tests
-        run: bun test
-
-  test-matrix:
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        runtime: [bun]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-      - run: bun install
-      - run: bun test

package/.takumi/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(connectors --help)"
-    ]
-  }
-}

package/CODE_OF_CONDUCT.md

@@ -1,31 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior:
-
-* The use of sexualized language or imagery and unwelcome sexual attention
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information without explicit permission
-* Other conduct which could reasonably be considered inappropriate
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -1,83 +0,0 @@
-# Contributing to open-knowledge
-
-Thank you for your interest in contributing!
-
-## Development Setup
-
-```bash
-# Clone the repo
-git clone https://github.com/hasna/knowledge.git
-cd knowledge
-
-# Install dependencies (Bun)
-bun install
-
-# Run tests
-bun test
-
-# Run a specific test file
-bun test tests/cli.test.ts
-```
-
-## Project Structure
-
-```
-knowledge/
-├── src/
-│   ├── cli.js    # CLI entry point, argument parsing, commands
-│   └── store.js  # Persistent store, file locking, ID generation
-├── tests/
-│   └── cli.test.ts  # Integration tests using Bun.test
-├── package.json
-└── LICENSE
-```
-
-## Design Principles
-
-**Agent-friendly first**: every output should be parseable by an LLM. Prefer `--json` for structured data. Keep error messages actionable.
-
-**Minimal dependencies**: keep the dependency footprint small. The store is a plain JSON file.
-
-**Safe by default**: destructive operations require explicit confirmation flags (`--yes`).
-
-**Concurrent-safe**: all store mutations go through `withLock()`. Do not bypass it.
-
-## Commit Conventions
-
-Use [Conventional Commits](https://www.conventionalcommits.org/):
-
-```
-feat(cli): add --tag filter on list command
-fix(store): handle empty store file gracefully
-docs(readme): add installation instructions
-```
-
-Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`
-
-## Pull Request Process
-
-1. Fork the repo and create a branch from `main`.
-2. Add tests for new functionality.
-3. Ensure all tests pass: `bun test`.
-4. Keep commits atomic and well-described.
-5. Open a PR with a clear description of the change and motivation.
-
-## Code Style
-
-- 2-space indentation
-- `for` loops over array methods where performance matters
-- Descriptive variable names
-- No unnecessary dependencies
-
-## Reporting Issues
-
-- Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.yml)
-- Search existing issues first
-- Include: Node/Bun version, OS, steps to reproduce, expected vs actual
-
-## Suggesting Features
-
-Open a [feature request issue](.github/ISSUE_TEMPLATE/feature_request.yml) describing:
-- The problem you're solving
-- How you envision the solution
-- Whether you're willing to implement it

package/FUNDING.yml

@@ -1 +0,0 @@
-github: hasna