@knolo/cli 3.2.1 → 4.0.0

package/templates/icp-knowledge-canister/frontend/src/App.tsx

@@ -0,0 +1,225 @@
+import { useEffect, useState, type FormEvent } from 'react';
+
+import { getClientConfig, getKnoloActor, type HitDto, type Opt, type PackInfo } from './canister';
+import './app.css';
+
+function readOpt<T>(value: Opt<T>): T | undefined {
+  return value[0];
+}
+
+function formatCount(value: Opt<bigint>): string {
+  const count = readOpt(value);
+  return count === undefined ? '--' : count.toString();
+}
+
+function formatScore(score: number): string {
+  return score.toFixed(3);
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+const clientConfig = getClientConfig();
+
+export default function App() {
+  const [packInfo, setPackInfo] = useState<PackInfo | null>(null);
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<HitDto[]>([]);
+  const [isPackLoading, setIsPackLoading] = useState(true);
+  const [isSearching, setIsSearching] = useState(false);
+  const [hasSearched, setHasSearched] = useState(false);
+  const [lastQuery, setLastQuery] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let active = true;
+
+    async function loadPackInfo() {
+      try {
+        const actor = await getKnoloActor();
+        const nextPackInfo = await actor.pack_info();
+        if (!active) {
+          return;
+        }
+
+        setPackInfo(nextPackInfo);
+        setError(null);
+      } catch (nextError) {
+        if (!active) {
+          return;
+        }
+
+        setError(formatError(nextError));
+      } finally {
+        if (active) {
+          setIsPackLoading(false);
+        }
+      }
+    }
+
+    void loadPackInfo();
+
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  async function handleSearch(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const trimmedQuery = query.trim();
+
+    if (!trimmedQuery) {
+      setResults([]);
+      setHasSearched(false);
+      return;
+    }
+
+    setIsSearching(true);
+    setHasSearched(true);
+    setLastQuery(trimmedQuery);
+    setError(null);
+
+    try {
+      const actor = await getKnoloActor();
+      const nextResults = await actor.search(trimmedQuery, 5);
+      setResults(nextResults);
+    } catch (nextError) {
+      setResults([]);
+      setError(formatError(nextError));
+    } finally {
+      setIsSearching(false);
+    }
+  }
+
+  const packLoaded = packInfo?.loaded ?? false;
+  const searchDisabled = isPackLoading || isSearching || !packLoaded || !query.trim();
+
+  return (
+    <main className="shell">
+      <section className="hero">
+        <div>
+          <p className="eyebrow">Direct browser client</p>
+          <h1>Knolo ICP Search</h1>
+          <p className="hero-copy">
+            Query the `knolo_knowledge` canister straight from the browser with `@dfinity/agent`.
+          </p>
+        </div>
+        <dl className="connection-card">
+          <div>
+            <dt>Replica</dt>
+            <dd>{clientConfig.host}</dd>
+          </div>
+          <div>
+            <dt>Network</dt>
+            <dd>{clientConfig.network}</dd>
+          </div>
+          <div>
+            <dt>Canister</dt>
+            <dd>{clientConfig.canisterId ?? 'Not configured'}</dd>
+          </div>
+        </dl>
+      </section>
+
+      <section className="panel-grid">
+        <article className="panel">
+          <div className="panel-header">
+            <h2>Pack status</h2>
+            <span className={`badge ${packLoaded ? 'loaded' : 'idle'}`}>
+              {isPackLoading ? 'Checking...' : packLoaded ? 'Loaded' : 'Idle'}
+            </span>
+          </div>
+
+          {isPackLoading ? (
+            <p className="muted">Checking pack status...</p>
+          ) : packLoaded && packInfo ? (
+            <dl className="stats-grid">
+              <div>
+                <dt>Label</dt>
+                <dd>{readOpt(packInfo.label) ?? '--'}</dd>
+              </div>
+              <div>
+                <dt>Version</dt>
+                <dd>{readOpt(packInfo.version)?.toString() ?? '--'}</dd>
+              </div>
+              <div>
+                <dt>Docs</dt>
+                <dd>{formatCount(packInfo.docs)}</dd>
+              </div>
+              <div>
+                <dt>Blocks</dt>
+                <dd>{formatCount(packInfo.blocks)}</dd>
+              </div>
+              <div>
+                <dt>Terms</dt>
+                <dd>{formatCount(packInfo.terms)}</dd>
+              </div>
+            </dl>
+          ) : (
+            <p className="empty-state">No pack loaded</p>
+          )}
+        </article>
+
+        <article className="panel">
+          <div className="panel-header">
+            <h2>Search</h2>
+            <span className="badge neutral">Top 5 hits</span>
+          </div>
+
+          <form className="search-form" onSubmit={handleSearch}>
+            <label className="search-label" htmlFor="search-input">
+              Search query
+            </label>
+            <div className="search-row">
+              <input
+                id="search-input"
+                className="search-input"
+                type="search"
+                value={query}
+                placeholder="Try alpha beta"
+                onChange={(event) => setQuery(event.target.value)}
+              />
+              <button className="search-button" type="submit" disabled={searchDisabled}>
+                {isSearching ? 'Searching...' : 'Search'}
+              </button>
+            </div>
+          </form>
+
+          {!packLoaded && !isPackLoading ? (
+            <p className="muted">
+              Load a `.knolo` pack into the canister first, then the browser client can query it.
+            </p>
+          ) : null}
+
+          {error ? <p className="error-box">{error}</p> : null}
+        </article>
+      </section>
+
+      <section className="panel results-panel">
+        <div className="panel-header">
+          <h2>Results</h2>
+          <span className="badge neutral">{results.length} items</span>
+        </div>
+
+        {results.length > 0 ? (
+          <ol className="results-list">
+            {results.map((result) => (
+              <li className="result-card" key={`${result.block_id.toString()}-${result.score}`}>
+                <div className="result-meta">
+                  <span>Source: {readOpt(result.source) ?? 'Unknown'}</span>
+                  <span>Namespace: {readOpt(result.namespace) ?? '--'}</span>
+                  <span>Score: {formatScore(result.score)}</span>
+                </div>
+                <p className="result-text">{result.text}</p>
+              </li>
+            ))}
+          </ol>
+        ) : hasSearched ? (
+          <p className="empty-state">No matches for "{lastQuery}".</p>
+        ) : (
+          <p className="muted">Run a search to inspect canister results here.</p>
+        )}
+      </section>
+    </main>
+  );
+}

package/templates/icp-knowledge-canister/frontend/src/app.css

@@ -0,0 +1,271 @@
+:root {
+  font-family: 'Avenir Next', 'Trebuchet MS', 'Segoe UI', sans-serif;
+  color: #132430;
+  background:
+    radial-gradient(circle at top left, rgba(253, 214, 146, 0.42), transparent 28%),
+    radial-gradient(circle at top right, rgba(130, 188, 196, 0.2), transparent 24%),
+    linear-gradient(180deg, #f7f4eb 0%, #eef2ec 100%);
+  line-height: 1.5;
+  font-weight: 400;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+button,
+input {
+  font: inherit;
+}
+
+#root {
+  min-height: 100vh;
+}
+
+.shell {
+  width: min(1120px, calc(100vw - 2rem));
+  margin: 0 auto;
+  padding: 2.5rem 0 3.5rem;
+}
+
+.hero {
+  display: grid;
+  grid-template-columns: minmax(0, 1.7fr) minmax(280px, 0.9fr);
+  gap: 1.5rem;
+  align-items: start;
+  margin-bottom: 1.5rem;
+}
+
+.eyebrow {
+  margin: 0 0 0.5rem;
+  text-transform: uppercase;
+  letter-spacing: 0.2em;
+  font-size: 0.78rem;
+  color: #7b5842;
+}
+
+h1,
+h2 {
+  margin: 0;
+  font-family: Georgia, 'Times New Roman', serif;
+  font-weight: 600;
+}
+
+h1 {
+  font-size: clamp(2.2rem, 4vw, 3.6rem);
+  line-height: 0.98;
+  max-width: 12ch;
+}
+
+.hero-copy {
+  margin: 1rem 0 0;
+  max-width: 55ch;
+  color: #3a4c56;
+}
+
+.connection-card,
+.panel {
+  background: rgba(255, 255, 255, 0.8);
+  border: 1px solid rgba(19, 36, 48, 0.08);
+  border-radius: 24px;
+  box-shadow: 0 22px 60px rgba(19, 36, 48, 0.08);
+  backdrop-filter: blur(12px);
+}
+
+.connection-card {
+  margin: 0;
+  padding: 1.25rem;
+  display: grid;
+  gap: 1rem;
+}
+
+.connection-card dt,
+.stats-grid dt {
+  margin: 0 0 0.35rem;
+  font-size: 0.78rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: #6c7b83;
+}
+
+.connection-card dd,
+.stats-grid dd {
+  margin: 0;
+  font-size: 0.96rem;
+  overflow-wrap: anywhere;
+}
+
+.panel-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1.5rem;
+  margin-bottom: 1.5rem;
+}
+
+.panel,
+.results-panel {
+  padding: 1.35rem;
+}
+
+.panel-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-bottom: 1rem;
+}
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  border-radius: 999px;
+  padding: 0.35rem 0.75rem;
+  font-size: 0.82rem;
+  font-weight: 600;
+}
+
+.badge.loaded {
+  background: rgba(79, 154, 117, 0.16);
+  color: #246243;
+}
+
+.badge.idle {
+  background: rgba(196, 143, 76, 0.14);
+  color: #8b5c24;
+}
+
+.badge.neutral {
+  background: rgba(40, 82, 99, 0.1);
+  color: #285263;
+}
+
+.stats-grid {
+  margin: 0;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1rem;
+}
+
+.search-form {
+  display: grid;
+  gap: 0.7rem;
+}
+
+.search-label {
+  font-weight: 600;
+  color: #223944;
+}
+
+.search-row {
+  display: flex;
+  gap: 0.75rem;
+}
+
+.search-input {
+  flex: 1;
+  min-width: 0;
+  border: 1px solid rgba(34, 57, 68, 0.18);
+  border-radius: 16px;
+  background: rgba(250, 250, 247, 0.95);
+  padding: 0.9rem 1rem;
+  color: #132430;
+}
+
+.search-input:focus {
+  outline: 2px solid rgba(42, 110, 132, 0.22);
+  border-color: rgba(42, 110, 132, 0.45);
+}
+
+.search-button {
+  border: 0;
+  border-radius: 16px;
+  background: linear-gradient(135deg, #1d5666 0%, #43807f 100%);
+  color: #fffdf8;
+  padding: 0.9rem 1.15rem;
+  min-width: 8.5rem;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.search-button:disabled {
+  cursor: not-allowed;
+  opacity: 0.58;
+}
+
+.muted,
+.empty-state {
+  margin: 1rem 0 0;
+  color: #52636d;
+}
+
+.empty-state {
+  font-weight: 600;
+}
+
+.error-box {
+  margin: 1rem 0 0;
+  padding: 0.85rem 1rem;
+  border-radius: 16px;
+  background: rgba(182, 63, 69, 0.08);
+  color: #8b232d;
+}
+
+.results-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: grid;
+  gap: 1rem;
+}
+
+.result-card {
+  border: 1px solid rgba(19, 36, 48, 0.08);
+  border-radius: 20px;
+  background: rgba(250, 249, 244, 0.9);
+  padding: 1rem;
+}
+
+.result-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.8rem 1rem;
+  margin-bottom: 0.7rem;
+  font-size: 0.88rem;
+  color: #52636d;
+}
+
+.result-text {
+  margin: 0;
+  white-space: pre-wrap;
+  color: #122631;
+}
+
+@media (max-width: 820px) {
+  .shell {
+    width: min(100vw - 1.2rem, 1120px);
+    padding-top: 1.5rem;
+  }
+
+  .hero,
+  .panel-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .search-row {
+    flex-direction: column;
+  }
+
+  .search-button {
+    width: 100%;
+  }
+
+  .stats-grid {
+    grid-template-columns: 1fr;
+  }
+}

package/templates/icp-knowledge-canister/frontend/src/canister.ts

@@ -0,0 +1,119 @@
+import { Actor, HttpAgent } from '@dfinity/agent';
+import type { ActorMethod, ActorSubclass } from '@dfinity/agent';
+import { IDL } from '@dfinity/candid';
+import type { InterfaceFactory } from '@dfinity/candid/lib/cjs/idl';
+
+import { resolveCanisterId, resolveNetwork, resolveReplicaHost } from './canisterConfig';
+
+export type Opt<T> = [] | [T];
+
+export interface HealthDto {
+  ok: boolean;
+  message: string;
+}
+
+export interface HitDto {
+  block_id: bigint;
+  score: number;
+  text: string;
+  source: Opt<string>;
+  namespace: Opt<string>;
+}
+
+export interface PackInfo {
+  loaded: boolean;
+  label: Opt<string>;
+  version: Opt<number>;
+  docs: Opt<bigint>;
+  blocks: Opt<bigint>;
+  terms: Opt<bigint>;
+}
+
+export interface KnoloService {
+  clear_pack: ActorMethod<[], HealthDto>;
+  health: ActorMethod<[], HealthDto>;
+  pack_info: ActorMethod<[], PackInfo>;
+  search: ActorMethod<[string, number], Array<HitDto>>;
+  set_pack: ActorMethod<[Uint8Array | number[], string], HealthDto>;
+}
+
+export const idlFactory: InterfaceFactory = ({ IDL: idl }) => {
+  const HealthDto = idl.Record({ ok: idl.Bool, message: idl.Text });
+  const PackInfo = idl.Record({
+    terms: idl.Opt(idl.Nat64),
+    docs: idl.Opt(idl.Nat64),
+    loaded: idl.Bool,
+    label: idl.Opt(idl.Text),
+    version: idl.Opt(idl.Nat32),
+    blocks: idl.Opt(idl.Nat64),
+  });
+  const HitDto = idl.Record({
+    block_id: idl.Nat64,
+    source: idl.Opt(idl.Text),
+    text: idl.Text,
+    score: idl.Float64,
+    namespace: idl.Opt(idl.Text),
+  });
+
+  return idl.Service({
+    clear_pack: idl.Func([], [HealthDto], []),
+    health: idl.Func([], [HealthDto], ['query']),
+    pack_info: idl.Func([], [PackInfo], ['query']),
+    search: idl.Func([idl.Text, idl.Nat32], [idl.Vec(HitDto)], ['query']),
+    set_pack: idl.Func([idl.Vec(idl.Nat8), idl.Text], [HealthDto], []),
+  });
+};
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function getClientConfig(locationLike: Pick<Location, 'hostname'> = window.location) {
+  const network = resolveNetwork(
+    import.meta.env.VITE_DFX_NETWORK ?? __KNOLO_DFX_NETWORK__,
+    locationLike.hostname
+  );
+  const host = resolveReplicaHost(locationLike.hostname, import.meta.env.VITE_IC_HOST);
+  const canisterId = resolveCanisterId(
+    import.meta.env.VITE_KNOLO_CANISTER_ID,
+    __KNOLO_CANISTER_ID__
+  );
+
+  return { canisterId, host, network };
+}
+
+let actorPromise: Promise<ActorSubclass<KnoloService>> | undefined;
+
+export async function getKnoloActor(): Promise<ActorSubclass<KnoloService>> {
+  if (!actorPromise) {
+    actorPromise = createKnoloActor().catch((error: unknown) => {
+      actorPromise = undefined;
+      throw error;
+    });
+  }
+
+  return actorPromise;
+}
+
+async function createKnoloActor(): Promise<ActorSubclass<KnoloService>> {
+  const config = getClientConfig();
+  if (!config.canisterId) {
+    throw new Error(
+      'Missing canister ID. Set VITE_KNOLO_CANISTER_ID or run dfx deploy in examples/icp-knowledge-canister.'
+    );
+  }
+
+  const agent = new HttpAgent({ host: config.host });
+  if (config.network !== 'ic') {
+    await agent.fetchRootKey().catch((error: unknown) => {
+      throw new Error(
+        `Unable to fetch the local replica root key from ${config.host}: ${formatError(error)}`
+      );
+    });
+  }
+
+  return Actor.createActor<KnoloService>(idlFactory, {
+    agent,
+    canisterId: config.canisterId,
+  });
+}

package/templates/icp-knowledge-canister/frontend/src/canisterConfig.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  IC_REPLICA_HOST,
+  LOCAL_REPLICA_HOST,
+  isLocalPage,
+  resolveCanisterId,
+  resolveNetwork,
+  resolveReplicaHost,
+} from './canisterConfig';
+
+describe('canister config helpers', () => {
+  it('prefers an explicit canister id', () => {
+    expect(resolveCanisterId('  aaaaa-aa  ', 'bbbbb-bb')).toBe('aaaaa-aa');
+  });
+
+  it('falls back to the dfx-derived canister id', () => {
+    expect(resolveCanisterId(undefined, ' bkyz2-fmaaa-aaaaa-qaaaq-cai ')).toBe(
+      'bkyz2-fmaaa-aaaaa-qaaaq-cai'
+    );
+  });
+
+  it('detects local pages and local replica defaults', () => {
+    expect(isLocalPage('localhost')).toBe(true);
+    expect(resolveNetwork(undefined, '127.0.0.1')).toBe('local');
+    expect(resolveReplicaHost('localhost', undefined)).toBe(LOCAL_REPLICA_HOST);
+  });
+
+  it('uses ic defaults away from localhost', () => {
+    expect(isLocalPage('knolo.example')).toBe(false);
+    expect(resolveNetwork(undefined, 'knolo.example')).toBe('ic');
+    expect(resolveReplicaHost('knolo.example', undefined)).toBe(IC_REPLICA_HOST);
+  });
+});

package/templates/icp-knowledge-canister/frontend/src/canisterConfig.ts

@@ -0,0 +1,26 @@
+export const LOCAL_REPLICA_HOST = 'http://127.0.0.1:4943';
+export const IC_REPLICA_HOST = 'https://icp-api.io';
+
+function trimValue(value: string | undefined | null): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function isLocalPage(hostname: string): boolean {
+  return hostname === '127.0.0.1' || hostname === 'localhost';
+}
+
+export function resolveNetwork(networkOverride: string | undefined, hostname: string): string {
+  return trimValue(networkOverride) ?? (isLocalPage(hostname) ? 'local' : 'ic');
+}
+
+export function resolveReplicaHost(hostname: string, hostOverride: string | undefined): string {
+  return trimValue(hostOverride) ?? (isLocalPage(hostname) ? LOCAL_REPLICA_HOST : IC_REPLICA_HOST);
+}
+
+export function resolveCanisterId(
+  explicitCanisterId: string | undefined,
+  fallbackCanisterId: string | undefined
+): string | undefined {
+  return trimValue(explicitCanisterId) ?? trimValue(fallbackCanisterId);
+}

package/templates/icp-knowledge-canister/frontend/src/main.tsx

@@ -0,0 +1,5 @@
+import ReactDOM from 'react-dom/client';
+
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);

package/templates/icp-knowledge-canister/frontend/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_DFX_NETWORK?: string;
+  readonly VITE_IC_HOST?: string;
+  readonly VITE_KNOLO_CANISTER_ID?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+
+declare const __KNOLO_CANISTER_ID__: string | undefined;
+declare const __KNOLO_DFX_NETWORK__: string;