@hasna/knowledge 0.2.26 → 0.2.28

package/docs/canonical-secrets-bootstrap-2026-06-08.md

@@ -0,0 +1,127 @@
+# Canonical Secrets Bootstrap Evidence: 2026-06-08
+
+Scope: canonical Hasna XYZ app secret paths in account `hasna-xyz-infra`
+(`789877399345`), region `us-east-1`, mirrored into the local `spark02`
+`secrets` vault.
+
+This note records names and migration intent only. It intentionally does not
+include secret payloads, passwords, API keys, connection strings, or `.env`
+contents.
+
+## Ownership Rule
+
+App-owned runtime/config secrets use:
+
+```txt
+hasna/xyz/{app_type}/{app}/prod/{component}
+```
+
+Shared infra/admin pointers use an infra-owned path:
+
+```txt
+hasna/xyz/infra/{resource_group}/prod/{component}/{role}
+```
+
+Legacy master credentials copied for migration are suffixed with
+`legacy-master`. They are deprecation inputs for migration jobs, not the clean
+runtime secret names new app code should read.
+
+## Open Files
+
+Created or verified in AWS Secrets Manager and the local vault:
+
+```txt
+hasna/xyz/opensource/files/prod/env
+hasna/xyz/opensource/files/prod/aws
+hasna/xyz/opensource/files/prod/s3
+hasna/xyz/opensource/files/prod/rds
+```
+
+Meaning:
+
+- `env`: app environment configuration.
+- `aws`: AWS account/profile/region and related app config metadata.
+- `s3`: canonical app storage bucket metadata for
+  `hasna-xyz-opensource-files-prod`.
+- `rds`: app runtime database connection fields for database `files` and role
+  `files_app`.
+
+The `aws` and `s3` entries are metadata-only. They do not contain access keys or
+tokens.
+
+## Open Knowledge
+
+Created or verified in AWS Secrets Manager and the local vault:
+
+```txt
+hasna/xyz/opensource/knowledge/prod/env
+hasna/xyz/opensource/knowledge/prod/aws
+hasna/xyz/opensource/knowledge/prod/s3
+```
+
+Meaning:
+
+- `env`: open-knowledge production app config metadata.
+- `aws`: AWS account/profile/region and related app config metadata.
+- `s3`: canonical app storage bucket metadata for
+  `hasna-xyz-opensource-knowledge-prod`.
+
+No `hasna/xyz/opensource/knowledge/prod/rds` secret was created in this pass.
+The OSS package is local-first and currently uses SQLite for local knowledge
+state. If a hosted wrapper later provisions an app database, the app-owned
+runtime secret should use:
+
+```txt
+hasna/xyz/opensource/knowledge/prod/rds
+```
+
+## Legacy Secret Mapping
+
+Mapped legacy AWS Secrets Manager names to canonical ownership paths:
+
+| Legacy name | Canonical path | Use |
+| --- | --- | --- |
+| `prod/microservice/rds/master` | `hasna/xyz/opensource/microservices/prod/rds/legacy-master` | Migration-only legacy master alias. |
+| `prod/connect/rds/master` | `hasna/xyz/opensource/connectors/prod/rds/legacy-master` | Migration-only legacy master alias. |
+| `internalapps/prod/rds/master` | `hasna/xyz/infra/apps/prod/postgres/legacy-internalapps-master` | Migration-only legacy shared/admin alias. |
+| `internalapps/prod/iapp-news/env` | `hasna/xyz/internalapp/news/prod/env` | Canonical app env path for internalapp `news`. |
+
+The three RDS aliases preserve old master credential payloads under explicit
+legacy names so migration jobs can read them without relying on noncanonical
+paths. They should not be used as the final runtime credentials for new app
+code. Clean app runtime database credentials should be provisioned under
+app-owned paths such as:
+
+```txt
+hasna/xyz/opensource/files/prod/rds
+hasna/xyz/internalapp/news/prod/rds
+```
+
+The shared canonical Postgres admin pointer remains:
+
+```txt
+hasna/xyz/infra/apps/prod/postgres/master
+```
+
+## Verification
+
+AWS Secrets Manager name-only verification returned these canonical entries:
+
+```txt
+hasna/xyz/infra/apps/prod/postgres/legacy-internalapps-master
+hasna/xyz/infra/apps/prod/postgres/master
+hasna/xyz/internalapp/news/prod/env
+hasna/xyz/opensource/connectors/prod/rds/legacy-master
+hasna/xyz/opensource/files/prod/aws
+hasna/xyz/opensource/files/prod/env
+hasna/xyz/opensource/files/prod/rds
+hasna/xyz/opensource/files/prod/s3
+hasna/xyz/opensource/knowledge/prod/aws
+hasna/xyz/opensource/knowledge/prod/env
+hasna/xyz/opensource/knowledge/prod/s3
+hasna/xyz/opensource/microservices/prod/rds/legacy-master
+```
+
+Local `secrets list` verification returned the same names with redacted values.
+
+No secret values were printed during creation or verification.

package/package.json

@@ -1,8 +1,16 @@
 {
   "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",
@@ -10,7 +18,7 @@
   },
   "files": [
     "bin",
-    "src",
+    "dist",
     "docs",
     "LICENSE",
     "README.md"
@@ -18,9 +26,8 @@
   "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",
@@ -49,12 +56,13 @@
     "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"
   },

package/src/agent.ts

@@ -1,367 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { migrateKnowledgeDb, openKnowledgeDb } from './knowledge-db';
-import { languageModelFor, normalizeAiSdkUsage, parseModelRef, recordProviderUsage, resolveModelRef } from './providers';
-import { retrieveKnowledgeContext, type KnowledgeContextPack, type RetrievalOptions } from './retrieval';
-import type { KnowledgeConfig } from './workspace';
-
-export interface KnowledgePromptOptions extends Omit<RetrievalOptions, 'query'> {
-  prompt: string;
-  generate?: boolean;
-  approveWrite?: boolean;
-  now?: Date;
-}
-
-export interface KnowledgePromptResult {
-  run_id: string;
-  prompt: string;
-  generated: boolean;
-  provider: string;
-  model: string;
-  answer: string;
-  context: KnowledgeContextPack;
-  citations: KnowledgeContextPack['citations'];
-  proposed_wiki_updates: Array<{
-    kind: 'answer_note';
-    title: string;
-    citations: string[];
-    requires_approval: boolean;
-  }>;
-  write_policy: {
-    approved: boolean;
-    durable_writes_performed: false;
-    reason: string;
-  };
-  usage: {
-    input_tokens: number;
-    output_tokens: number;
-    cost_usd: number;
-  };
-  warnings: string[];
-}
-
-function estimateTokens(text: string): number {
-  const words = text.trim().split(/\s+/).filter(Boolean).length;
-  return Math.max(1, Math.ceil(words * 1.25));
-}
-
-function citationLabel(index: number): string {
-  return `C${index + 1}`;
-}
-
-function localAnswer(prompt: string, context: KnowledgeContextPack): string {
-  if (context.excerpts.length === 0) {
-    return `No indexed knowledge matched the prompt: ${prompt}`;
-  }
-  const lines = [
-    `Found ${context.excerpts.length} relevant knowledge excerpt(s) for: ${prompt}`,
-    '',
-    ...context.excerpts.slice(0, 5).map((excerpt, index) => {
-      const citation = context.citations.find((entry) => entry.id === excerpt.citation_id);
-      const ref = citation?.source_ref ?? citation?.source_uri ?? citation?.artifact_path ?? citation?.artifact_uri ?? 'unknown source';
-      return `[${citationLabel(index)}] ${excerpt.text} (${ref})`;
-    }),
-  ];
-  return lines.join('\n');
-}
-
-function promptForModel(prompt: string, context: KnowledgeContextPack): string {
-  const citations = context.citations.map((citation, index) => ({
-    id: citationLabel(index),
-    source_ref: citation.source_ref,
-    source_uri: citation.source_uri,
-    artifact_path: citation.artifact_path,
-    revision: citation.revision,
-    hash: citation.hash,
-    quote: citation.quote,
-  }));
-  const excerpts = context.excerpts.map((excerpt, index) => ({
-    id: citationLabel(index),
-    kind: excerpt.kind,
-    text: excerpt.text,
-    score: excerpt.score,
-  }));
-  return [
-    `Prompt: ${prompt}`,
-    '',
-    'Use only the provided context. Cite claims with citation ids like [C1]. If context is insufficient, say what is missing.',
-    '',
-    `Context excerpts:\n${JSON.stringify(excerpts, null, 2)}`,
-    '',
-    `Citations:\n${JSON.stringify(citations, null, 2)}`,
-  ].join('\n');
-}
-
-function proposedUpdates(prompt: string, context: KnowledgeContextPack): KnowledgePromptResult['proposed_wiki_updates'] {
-  if (context.citations.length === 0) return [];
-  return [{
-    kind: 'answer_note',
-    title: prompt.length > 80 ? `${prompt.slice(0, 77)}...` : prompt,
-    citations: context.citations.map((citation) => citation.id),
-    requires_approval: true,
-  }];
-}
-
-function insertRun(dbPath: string, input: {
-  runId: string;
-  prompt: string;
-  status: string;
-  provider: string;
-  model: string;
-  metadata: Record<string, unknown>;
-  now: string;
-}): void {
-  const db = openKnowledgeDb(dbPath);
-  try {
-    db.run(
-      `INSERT INTO runs (id, type, prompt, status, provider, model, metadata_json, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-      [
-        input.runId,
-        'knowledge-prompt',
-        input.prompt,
-        input.status,
-        input.provider,
-        input.model,
-        JSON.stringify(input.metadata),
-        input.now,
-        input.now,
-      ],
-    );
-  } finally {
-    db.close();
-  }
-}
-
-function addRunEvent(dbPath: string, input: {
-  runId: string;
-  level: 'info' | 'warn' | 'error';
-  event: string;
-  metadata: Record<string, unknown>;
-  now: string;
-}): void {
-  const db = openKnowledgeDb(dbPath);
-  try {
-    db.run(
-      `INSERT INTO run_events (id, run_id, level, event, metadata_json, created_at)
-       VALUES (?, ?, ?, ?, ?, ?)`,
-      [
-        `evt_${randomUUID()}`,
-        input.runId,
-        input.level,
-        input.event,
-        JSON.stringify(input.metadata),
-        input.now,
-      ],
-    );
-  } finally {
-    db.close();
-  }
-}
-
-function updateRun(dbPath: string, input: {
-  runId: string;
-  status: string;
-  provider: string;
-  model: string;
-  metadata: Record<string, unknown>;
-  now: string;
-}): void {
-  const db = openKnowledgeDb(dbPath);
-  try {
-    db.run(
-      `UPDATE runs
-       SET status = ?, provider = ?, model = ?, metadata_json = ?, updated_at = ?
-       WHERE id = ?`,
-      [
-        input.status,
-        input.provider,
-        input.model,
-        JSON.stringify(input.metadata),
-        input.now,
-        input.runId,
-      ],
-    );
-  } finally {
-    db.close();
-  }
-}
-
-function recordUsage(dbPath: string, runId: string, usage: KnowledgePromptResult['usage'], provider: string, model: string, now: string, metadata: Record<string, unknown> = {}): void {
-  const db = openKnowledgeDb(dbPath);
-  try {
-    recordProviderUsage(db, {
-      run_id: runId,
-      provider,
-      model,
-      input_tokens: usage.input_tokens,
-      output_tokens: usage.output_tokens,
-      cost_usd: usage.cost_usd,
-      metadata,
-      created_at: now,
-    });
-  } finally {
-    db.close();
-  }
-}
-
-export async function runKnowledgePrompt(options: KnowledgePromptOptions): Promise<KnowledgePromptResult> {
-  const prompt = options.prompt.trim();
-  if (!prompt) throw new Error('Knowledge prompt is required.');
-  const now = (options.now ?? new Date()).toISOString();
-  const runId = `run_${randomUUID()}`;
-  const modelRef = resolveModelRef(options.modelRef ?? 'default', options.config);
-  const parsed = parseModelRef(modelRef);
-
-  migrateKnowledgeDb(options.dbPath);
-  insertRun(options.dbPath, {
-    runId,
-    prompt,
-    status: options.generate ? 'running' : 'dry_run',
-    provider: options.generate ? parsed.provider : 'local',
-    model: options.generate ? parsed.model : 'context-draft',
-    metadata: {
-      semantic: options.semantic === true || options.fake === true || Boolean(options.modelRef),
-      approve_write: options.approveWrite === true,
-      generated: options.generate === true,
-    },
-    now,
-  });
-
-  const { prompt: _prompt, generate: _generate, approveWrite: _approveWrite, now: _now, ...retrievalOptions } = options;
-  const context = await retrieveKnowledgeContext({
-    ...retrievalOptions,
-    query: prompt,
-  });
-  addRunEvent(options.dbPath, {
-    runId,
-    level: 'info',
-    event: 'context_retrieved',
-    metadata: {
-      results: context.results.length,
-      citations: context.citations.length,
-      warnings: context.warnings,
-    },
-    now,
-  });
-
-  let answer = localAnswer(prompt, context);
-  let generated = false;
-  let provider = 'local';
-  let model = 'context-draft';
-  let usage = {
-    input_tokens: estimateTokens(prompt) + context.excerpts.reduce((sum, excerpt) => sum + estimateTokens(excerpt.text), 0),
-    output_tokens: estimateTokens(answer),
-    cost_usd: 0,
-  };
-  const warnings = [...context.warnings];
-
-  if (options.generate) {
-    try {
-      if (options.fake) {
-        generated = true;
-        provider = parsed.provider;
-        model = parsed.model;
-        answer = `Fake generated answer for: ${prompt}\n\n${answer}`;
-      } else {
-        const { generateText } = await import('ai');
-        const languageModel = await languageModelFor(modelRef, {
-          config: options.config,
-          env: options.env,
-        });
-        const result = await generateText({
-          model: languageModel as never,
-          system: 'You answer company knowledge-base prompts using only provided context and citation ids.',
-          prompt: promptForModel(prompt, context),
-        });
-        generated = true;
-        provider = parsed.provider;
-        model = parsed.model;
-        answer = result.text;
-        const normalized = normalizeAiSdkUsage({
-          provider,
-          model,
-          usage: result.usage as Record<string, unknown> | undefined,
-          providerMetadata: result.providerMetadata as Record<string, unknown> | undefined,
-        });
-        usage = {
-          input_tokens: normalized.input_tokens,
-          output_tokens: normalized.output_tokens,
-          cost_usd: normalized.cost_usd,
-        };
-      }
-    } catch (error) {
-      addRunEvent(options.dbPath, {
-        runId,
-        level: 'error',
-        event: 'answer_generation_failed',
-        metadata: { message: error instanceof Error ? error.message : String(error) },
-        now,
-      });
-      updateRun(options.dbPath, {
-        runId,
-        status: 'failed',
-        provider: parsed.provider,
-        model: parsed.model,
-        metadata: {
-          generated: false,
-          error: error instanceof Error ? error.message : String(error),
-        },
-        now,
-      });
-      throw error;
-    }
-  }
-
-  const updates = proposedUpdates(prompt, context);
-  const writePolicy = {
-    approved: options.approveWrite === true,
-    durable_writes_performed: false as const,
-    reason: options.approveWrite
-      ? 'Approval flag recorded; durable wiki writing is deferred to the wiki compile task.'
-      : 'Dry-run mode: proposed wiki updates require approval before durable writes.',
-  };
-  addRunEvent(options.dbPath, {
-    runId,
-    level: 'info',
-    event: generated ? 'answer_generated' : 'answer_drafted',
-    metadata: {
-      provider,
-      model,
-      proposed_updates: updates.length,
-      durable_writes_performed: false,
-    },
-    now,
-  });
-  recordUsage(options.dbPath, runId, usage, provider, model, now, {
-    generated,
-    citations: context.citations.length,
-  });
-  updateRun(options.dbPath, {
-    runId,
-    status: generated ? 'completed' : 'dry_run',
-    provider,
-    model,
-    metadata: {
-      generated,
-      citations: context.citations.length,
-      proposed_updates: updates.length,
-      approve_write: options.approveWrite === true,
-    },
-    now,
-  });
-
-  return {
-    run_id: runId,
-    prompt,
-    generated,
-    provider,
-    model,
-    answer,
-    context,
-    citations: context.citations,
-    proposed_wiki_updates: updates,
-    write_policy: writePolicy,
-    usage,
-    warnings,
-  };
-}