@hasna/knowledge 0.2.26 → 0.2.28

package/README.md

@@ -32,6 +32,47 @@ Or run directly:
 bun x @hasna/knowledge add "My Note" "Some content"
 ```
 
+## SDK
+
+Apps can install the package and use the public SDK without shelling out to the
+CLI or importing internal source files:
+
+```ts
+import { createKnowledgeClient } from '@hasna/knowledge';
+
+const knowledge = createKnowledgeClient({
+  scope: 'project',
+  cwd: process.cwd(),
+});
+
+await knowledge.setup({ mode: 'hosted', canonicalHasnaXyz: true });
+await knowledge.ingest.source('file:///absolute/path/to/handbook.md', 'knowledge_index');
+
+const results = await knowledge.search({
+  query: 'company wiki policy',
+  semantic: true,
+  limit: 5,
+});
+
+const answer = await knowledge.ask('How do we cite handbook policy?', {
+  semantic: true,
+  limit: 5,
+});
+```
+
+The stable package surface is the top-level `@hasna/knowledge` export:
+`createKnowledgeClient`, `createKnowledgeSdk`, service/result types, workspace
+helpers, source-ref helpers, storage contracts, search/retrieval types,
+provider helpers, and remote contract types. CLI and MCP entrypoints remain
+available as package bins.
+
+The SDK uses the same `.hasna/apps/knowledge` project workspace as the CLI. In
+local mode it writes the SQLite catalog and generated artifacts under that path.
+In hosted/canonical mode it can point generated artifacts at S3 while keeping
+raw source ownership outside open-knowledge. Source files remain referenced via
+`open-files://`, `file://`, `s3://`, or web refs; open-knowledge stores derived
+chunks, citations, indexes, run logs, and generated wiki artifacts.
+
 ## Quick Start
 
 ```bash
@@ -229,10 +270,26 @@ knowledge bucket/prefix while `open-files` remains the source of truth for raw
 source bytes. The command also reports artifact classes, allowed source ref
 schemes, and warnings for non-scalable or unsafe config.
 
+For Hasna XYZ production, the canonical generated-artifact bucket is
+`hasna-xyz-opensource-knowledge-prod` in `us-east-1` with prefix
+`.hasna/apps/knowledge/`. `storage status --json` exposes this under
+`canonical_hasna_xyz` even when local storage is active. The canonical
+metadata-only secret paths are:
+
+```text
+hasna/xyz/opensource/knowledge/prod/env
+hasna/xyz/opensource/knowledge/prod/aws
+hasna/xyz/opensource/knowledge/prod/s3
+```
+
+The future hosted database path, if provisioned, is
+`hasna/xyz/opensource/knowledge/prod/rds`.
+
 ### setup / auth / remote
 ```bash
 open-knowledge setup --mode local [--scope project] [--json]
 open-knowledge setup --mode hosted [--api-url https://knowledge.hasna.xyz] [--scope project] [--json]
+open-knowledge setup --mode hosted --canonical-hasna-xyz [--scope project] [--json]
 open-knowledge auth login --api-key <key> [--email you@example.com] [--org <slug>] [--scope project] [--json]
 open-knowledge auth whoami [--scope project] [--json]
 open-knowledge auth logout [--scope project] [--json]
@@ -518,6 +575,10 @@ prompt, embedding, or agent command explicitly requests a model.
 
 Generated knowledge artifacts can be stored locally under
 `.hasna/apps/knowledge/artifacts` or through the S3 artifact-store adapter.
+For Hasna XYZ production, `open-knowledge setup --mode hosted
+--canonical-hasna-xyz --scope project --json` configures generated artifacts
+under `s3://hasna-xyz-opensource-knowledge-prod/.hasna/apps/knowledge/` and
+keeps `open-files` as the raw-source owner.
 
 The default safety policy allows writes only under the resolved
 `.hasna/apps/knowledge` workspace. S3 manifest/outbox reads require

package/bin/open-knowledge-mcp.js

@@ -13660,9 +13660,17 @@ import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync
 // package.json
 var package_default = {
   name: "@hasna/knowledge",
-  version: "0.2.26",
+  version: "0.2.28",
   description: "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   type: "module",
+  exports: {
+    ".": {
+      import: "./dist/index.js",
+      types: "./dist/index.d.ts"
+    }
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
   bin: {
     knowledge: "bin/open-knowledge.js",
     "open-knowledge": "bin/open-knowledge.js",
@@ -13670,7 +13678,7 @@ var package_default = {
   },
   files: [
     "bin",
-    "src",
+    "dist",
     "docs",
     "LICENSE",
     "README.md"
@@ -13678,9 +13686,8 @@ var package_default = {
   scripts: {
     test: "bun test",
     "test:cli": "bun test tests/cli.test.ts",
-    build: "bun build --target=bun --outfile=bin/open-knowledge.js --minify --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/cli.ts && bun build --target=bun --outfile=bin/open-knowledge-mcp.js --external @modelcontextprotocol/sdk --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/mcp.js",
-    prepublishOnly: "bun run build",
-    postinstall: "bun run build"
+    build: "rm -rf dist && bun build --target=bun --outfile=bin/open-knowledge.js --minify --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/cli.ts && bun build --target=bun --outfile=bin/open-knowledge-mcp.js --external @modelcontextprotocol/sdk --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/mcp.js && bun build ./src/index.ts --outdir ./dist --target bun --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek && bunx tsc -p tsconfig.build.json",
+    prepublishOnly: "bun run build"
   },
   keywords: [
     "knowledge",
@@ -13709,12 +13716,13 @@ var package_default = {
     node: ">=18"
   },
   dependencies: {
-    "@aws-sdk/client-s3": "^3.1063.0",
-    "@aws-sdk/credential-providers": "^3.1063.0",
     "@ai-sdk/anthropic": "^3.0.81",
     "@ai-sdk/deepseek": "^2.0.35",
     "@ai-sdk/openai": "^3.0.68",
+    "@aws-sdk/client-s3": "^3.1063.0",
+    "@aws-sdk/credential-providers": "^3.1063.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/json-schema": "^7.0.15",
     ai: "^6.0.197",
     zod: "^4.3.6"
   },
@@ -13731,6 +13739,42 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { dirname, join, resolve } from "path";
 var HASNA_KNOWLEDGE_APP_PATH = join(".hasna", "apps", "knowledge");
+var 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"
+};
+function canonicalHasnaXyzKnowledgeStorage() {
+  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
+    }
+  };
+}
 function legacyGlobalStorePath() {
   return join(homedir(), ".open-knowledge", "db.json");
 }
@@ -18115,6 +18159,9 @@ function resolveStorageContract(config2, workspace, scope = "global") {
   const s3 = config2.storage.s3 ?? null;
   const prefix = s3?.prefix?.replace(/^\/+|\/+$/g, "") ?? "";
   const s3UriPrefix = s3 ? `s3://${s3.bucket}/${prefix ? `${prefix}/` : ""}` : "";
+  const canonicalPrefix = HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.prefix.replace(/^\/+|\/+$/g, "");
+  const canonicalS3UriPrefix = `s3://${HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.bucket}/${canonicalPrefix}/`;
+  const canonicalActive = config2.storage.type === "s3" && s3?.bucket === HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.bucket && (s3.region ?? null) === HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.region;
   return {
     scope,
     mode: config2.mode,
@@ -18149,6 +18196,30 @@ function resolveStorageContract(config2, workspace, scope = "global") {
         kms_key_configured: Boolean(s3.kms_key_id)
       } : null
     },
+    canonical_hasna_xyz: {
+      division: HASNA_XYZ_KNOWLEDGE_CANONICAL.division,
+      app_type: HASNA_XYZ_KNOWLEDGE_CANONICAL.app_type,
+      app: HASNA_XYZ_KNOWLEDGE_CANONICAL.app,
+      env: HASNA_XYZ_KNOWLEDGE_CANONICAL.env,
+      active: canonicalActive,
+      local_path: HASNA_XYZ_KNOWLEDGE_CANONICAL.local_path,
+      s3: {
+        bucket: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.bucket,
+        region: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.region,
+        profile: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.profile,
+        prefix: canonicalPrefix,
+        uri_prefix: canonicalS3UriPrefix,
+        server_side_encryption: HASNA_XYZ_KNOWLEDGE_CANONICAL.s3.server_side_encryption
+      },
+      secrets: {
+        env: HASNA_XYZ_KNOWLEDGE_CANONICAL.secrets.env,
+        aws: HASNA_XYZ_KNOWLEDGE_CANONICAL.secrets.aws,
+        s3: HASNA_XYZ_KNOWLEDGE_CANONICAL.secrets.s3,
+        rds: HASNA_XYZ_KNOWLEDGE_CANONICAL.secrets.rds,
+        future_rds: HASNA_XYZ_KNOWLEDGE_CANONICAL.secrets.future_rds
+      },
+      evidence_doc: HASNA_XYZ_KNOWLEDGE_CANONICAL.evidence_doc
+    },
     hosted: {
       enabled: config2.mode === "hosted",
       api_url: normalizeKnowledgeApiOrigin(config2.hosted?.api_url ?? DEFAULT_KNOWLEDGE_API_URL),
@@ -19058,16 +19129,21 @@ class KnowledgeService {
       hosted: {
         ...current.hosted ?? {},
         ...apiUrl ? { api_url: apiUrl } : {}
-      }
+      },
+      storage: options.canonicalHasnaXyz ? canonicalHasnaXyzKnowledgeStorage() : current.storage
     };
     writeKnowledgeConfig(workspace.configPath, nextConfig);
     this.cachedConfig = nextConfig;
+    const storage = resolveStorageContract(nextConfig, workspace, this.scope);
     return {
       ok: true,
       mode,
       api_url: nextConfig.hosted?.api_url ?? null,
+      storage_type: nextConfig.storage.type,
+      artifact_uri_prefix: storage.artifact_store.uri_prefix,
+      canonical_hasna_xyz: storage.canonical_hasna_xyz,
       config_path: workspace.configPath,
-      next: mode === "hosted" ? ["open-knowledge auth login --api-key <key>", "open-knowledge remote contracts --json"] : ["open-knowledge search <query>", "knowledge <prompt>"],
+      next: mode === "hosted" ? ["open-knowledge auth login --api-key <key>", "open-knowledge storage status --json", "open-knowledge remote contracts --json"] : ["open-knowledge search <query>", "knowledge <prompt>"],
       message: `Set knowledge mode to ${mode}`
     };
   }