@dayofweek/dcli 1.4.0 → 1.5.0

package/README.md

@@ -85,6 +85,32 @@ https://field.dayofweek.com/brain/<areaId>/source/<sourceId>
 
 Unknown hosts, user-info, ports, query strings, fragments, encoded path separators, malformed identifiers, and oversized input are rejected before any API request.
 
+## Entity knowledge
+
+Knowledge documents attached to an entity — read them, add to them, mirror them
+out into another knowledge base.
+
+```bash
+# Read
+dcli knowledge list --entity <entityId> --json
+dcli knowledge list --entity <entityId> --full --json    # whole content, not excerpts
+dcli knowledge get <documentId> --json
+dcli knowledge search "cold chain" --entity <entityId> --json
+
+# Add a markdown note — submitted for human review
+dcli knowledge add --entity <entityId> --title "Variety catalogue" --file note.md
+
+# Mirror an entity's sources to disk as markdown with provenance front-matter
+dcli knowledge export --entity <entityId> --out ./knowledge
+```
+
+`add` submits a proposal by default: a person approves it before it lands. If
+your token has admin rights you can pass `--direct` to skip review, and
+`dcli knowledge attach --file article.pdf` to upload a binary source. Both write
+immediately, so treat them as something you do when a person has asked for that
+specific document — not as the normal path. The server rejects them for
+non-admin tokens.
+
 ## Legacy platform commands
 
 Existing read/proposal workflows remain compatible:

package/dist/bin/dcli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { ApiError, DayOfWeekClient } from "../client.js";
+import { ApiError, DayOfWeekClient, toArrayBuffer } from "../client.js";
 import { getToken, getApiUrl, saveConfig, loadConfig, saveCredential, deleteCredential } from "../config.js";
 import { browserLogin } from "../auth/login.js";
 import { parseBrainResource } from "../uri.js";
-import { accessSync, constants, readFileSync, existsSync, statSync } from "node:fs";
+import { accessSync, constants, mkdirSync, readFileSync, existsSync, statSync, writeFileSync } from "node:fs";
 import { join, basename, resolve, relative, sep } from "node:path";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline/promises";
@@ -462,6 +462,191 @@ agent
     const result = await client.getProposal(proposalId);
     output(result);
 });
+// ── Knowledge Commands ───────────────────────────────────────────────────────
+const MIME_BY_EXT = {
+    ".pdf": "application/pdf",
+    ".md": "text/markdown",
+    ".txt": "text/plain",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".html": "text/html",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".doc": "application/msword",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".xls": "application/vnd.ms-excel",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+function guessMimeType(path) {
+    const dot = path.lastIndexOf(".");
+    const ext = dot === -1 ? "" : path.slice(dot).toLowerCase();
+    return MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+/** Filesystem-safe name for an exported document, keeping it recognisable. */
+function exportFileName(doc) {
+    const base = (doc.fileName || doc.title || doc.id || "document").trim();
+    const stripped = base.replace(/\.(md|txt)$/i, "");
+    const safe = stripped.replace(/[/\\:*?"<>|]+/g, "-").replace(/\s+/g, " ").slice(0, 120);
+    return `${safe || doc.id || "document"}.md`;
+}
+const knowledge = program
+    .command("knowledge")
+    .description("Read, add and export entity knowledge documents");
+knowledge
+    .command("list")
+    .description("List knowledge documents on an entity")
+    .requiredOption("--entity <entityId>", "Target entity id")
+    .option("--full", "Include each document's full content, not an excerpt")
+    .option("--org <org>", "Organization (admin only)")
+    .action(async (opts) => {
+    const client = getClient();
+    output(await client.listKnowledge({ entity: opts.entity, full: opts.full, org: opts.org }));
+});
+knowledge
+    .command("get <documentId>")
+    .description("Show one knowledge document with full content")
+    .option("--org <org>", "Organization (admin only)")
+    .action(async (documentId, opts) => {
+    const client = getClient();
+    output(await client.getKnowledge(documentId, opts.org));
+});
+knowledge
+    .command("search <query>")
+    .description("Semantic search across knowledge documents")
+    .option("--entity <entityId>", "Scope to one entity's org tree")
+    .option("--types <types>", "Comma-separated sourceType filter")
+    .option("--limit <count>", "Max hits", parseInt)
+    .option("--all-orgs", "Search every org (admin only)")
+    .option("--org <org>", "Organization (admin only)")
+    .action(async (query, opts) => {
+    const client = getClient();
+    output(await client.searchKnowledge({
+        query,
+        entity: opts.entity,
+        types: opts.types
+            ? String(opts.types).split(",").map((t) => t.trim()).filter(Boolean)
+            : undefined,
+        limit: opts.limit,
+        allOrgs: opts.allOrgs,
+        org: opts.org,
+    }));
+});
+knowledge
+    .command("add")
+    .description("Add a markdown knowledge note (proposal by default)")
+    .requiredOption("--entity <entityId>", "Target entity id")
+    .requiredOption("--title <title>", "Document title")
+    .option("--file <path>", "Markdown file to read (- for stdin)")
+    .option("--content <text>", "Inline content instead of --file")
+    .option("--source-type <type>", "research | website | competitive_intel | …", "research")
+    .option("--source-url <url>", "Where the content came from")
+    .option("--source-description <text>", "Short provenance note")
+    .option("--confidence <n>", "0-1, helps reviewers prioritize", parseFloat)
+    .option("--source-agent <name>", "Attribution for the submitting agent")
+    .option("--direct", "Write immediately instead of proposing. Admin only — ask the operator first")
+    .option("--org <org>", "Organization (admin only)")
+    .action(async (opts) => {
+    let content;
+    if (opts.content) {
+        content = String(opts.content);
+    }
+    else if (opts.file) {
+        content = opts.file === "-" ? readFileSync(0, "utf8") : readFileSync(opts.file, "utf8");
+    }
+    else {
+        throw new Error("Provide --file or --content");
+    }
+    if (!content.trim())
+        throw new Error("Content is empty");
+    const client = getClient();
+    output(await client.addKnowledge({
+        entityId: opts.entity,
+        title: opts.title,
+        content,
+        sourceType: opts.sourceType,
+        sourceUrl: opts.sourceUrl,
+        sourceDescription: opts.sourceDescription,
+        confidence: opts.confidence,
+        sourceAgent: opts.sourceAgent,
+        direct: Boolean(opts.direct),
+        org: opts.org,
+    }));
+});
+knowledge
+    .command("attach")
+    .description("Attach a file (PDF, DOCX, XLSX …) as a source. Admin only")
+    .requiredOption("--entity <entityId>", "Target entity id")
+    .requiredOption("--file <path>", "File to upload")
+    .option("--name <fileName>", "Stored file name (defaults to the file's own)")
+    .option("--mime <mimeType>", "Content type (guessed from the extension)")
+    .option("--source-type <type>", "research | website | contract | …", "other")
+    .option("--source-url <url>", "Where the file came from")
+    .option("--source-description <text>", "Short provenance note")
+    .option("--org <org>", "Organization (admin only)")
+    .action(async (opts) => {
+    if (!existsSync(opts.file))
+        throw new Error(`File not found: ${opts.file}`);
+    const data = readFileSync(opts.file);
+    if (data.byteLength === 0)
+        throw new Error("File is empty");
+    const client = getClient();
+    output(await client.attachKnowledgeFile({
+        entityId: opts.entity,
+        data: toArrayBuffer(data),
+        fileName: opts.name ?? basename(opts.file),
+        mimeType: opts.mime ?? guessMimeType(opts.file),
+        sourceType: opts.sourceType,
+        sourceUrl: opts.sourceUrl,
+        sourceDescription: opts.sourceDescription,
+        org: opts.org,
+    }));
+});
+knowledge
+    .command("export")
+    .description("Write an entity's knowledge documents to disk as markdown")
+    .requiredOption("--entity <entityId>", "Source entity id")
+    .requiredOption("--out <dir>", "Directory to write into (created if missing)")
+    .option("--org <org>", "Organization (admin only)")
+    .action(async (opts) => {
+    const client = getClient();
+    const docs = await client.listKnowledge({ entity: opts.entity, full: true, org: opts.org });
+    mkdirSync(opts.out, { recursive: true });
+    const written = [];
+    const skipped = [];
+    for (const doc of docs) {
+        const body = typeof doc.content === "string" ? doc.content : "";
+        if (!body) {
+            // A binary source whose text extraction hasn't finished has nothing to
+            // mirror yet. Report it rather than writing an empty file.
+            skipped.push({
+                id: doc.id,
+                title: doc.title,
+                reason: doc.processingStatus && doc.processingStatus !== "completed"
+                    ? `processingStatus=${doc.processingStatus}`
+                    : "no extracted content",
+            });
+            continue;
+        }
+        const frontMatter = [
+            "---",
+            `document_id: ${doc.id}`,
+            `title: ${JSON.stringify(doc.title ?? "")}`,
+            `source_type: ${doc.sourceType ?? "other"}`,
+            ...(doc.sourceUrl ? [`source_url: ${doc.sourceUrl}`] : []),
+            ...(doc.sourceDescription
+                ? [`source_description: ${JSON.stringify(doc.sourceDescription)}`]
+                : []),
+            `entity_id: ${opts.entity}`,
+            ...(doc.createdAt ? [`created_at: ${new Date(doc.createdAt).toISOString()}`] : []),
+            "exported_from: dayofweek-platform",
+            "---",
+            "",
+        ].join("\n");
+        const target = join(opts.out, exportFileName(doc));
+        writeFileSync(target, `${frontMatter}${body}\n`, "utf8");
+        written.push({ id: doc.id, file: target, bytes: Buffer.byteLength(body, "utf8") });
+    }
+    output({ entity: opts.entity, out: opts.out, total: docs.length, written, skipped });
+});
 // ── Skill Commands ───────────────────────────────────────────────────────────
 const skill = program.command("skill").description("Manage the Day of Week agent skill");
 function resolveTargetDirs(target, bundleName, customDir) {

package/dist/client.d.ts

@@ -2,6 +2,11 @@
  * HTTP client for the Day of Week platform REST API.
  * All calls go through the proxy at field.dayofweek.com/app/api/dcli.
  */
+/**
+ * Node's Buffer is a Uint8Array view over a possibly-larger, possibly-shared
+ * backing store, which is not assignable to BodyInit. Copy out the exact bytes.
+ */
+export declare function toArrayBuffer(view: Uint8Array): ArrayBuffer;
 export declare class ApiError extends Error {
     status: number;
     code?: string | undefined;
@@ -154,6 +159,64 @@ export declare class DayOfWeekClient {
         truncated: boolean;
         total: number;
     }>;
+    /**
+     * List the knowledge documents attached to an entity. `full` returns each
+     * document's whole content instead of an excerpt, which is what you want when
+     * mirroring an entity's sources into an external knowledge base.
+     */
+    listKnowledge(opts: {
+        entity: string;
+        full?: boolean;
+        org?: string;
+    }): Promise<any[]>;
+    getKnowledge(documentId: string, org?: string): Promise<any>;
+    /** Semantic search across knowledge documents. */
+    searchKnowledge(opts: {
+        query: string;
+        entity?: string;
+        types?: string[];
+        limit?: number;
+        allOrgs?: boolean;
+        org?: string;
+    }): Promise<any>;
+    /**
+     * Add a markdown knowledge note.
+     *
+     * Without `direct` this submits a proposal for human review — the default,
+     * and the only option non-admin tokens have. With `direct: true` an admin
+     * token writes the document immediately, skipping review. Ask the operator
+     * before doing that; see references/admin.md in the served skill.
+     */
+    addKnowledge(input: {
+        entityId: string;
+        title: string;
+        content: string;
+        sourceType?: string;
+        sourceUrl?: string;
+        sourceDescription?: string;
+        confidence?: number;
+        sourceAgent?: string;
+        direct?: boolean;
+        org?: string;
+    }): Promise<any>;
+    /**
+     * Attach a binary source (PDF, DOCX, XLSX, …) to an entity. Admin only.
+     *
+     * Three hops: ask for an upload URL, send the bytes straight to Convex
+     * storage, then register the resulting storageId. The bytes never pass
+     * through function arguments, so file size isn't bounded by an arg limit.
+     */
+    attachKnowledgeFile(input: {
+        entityId: string;
+        /** Raw file bytes. Buffer callers: pass `toArrayBuffer(buf)` below. */
+        data: ArrayBuffer;
+        fileName: string;
+        mimeType: string;
+        sourceType?: string;
+        sourceUrl?: string;
+        sourceDescription?: string;
+        org?: string;
+    }): Promise<any>;
     getSkillBundle(name?: string): Promise<{
         name: string;
         version: string;
@@ -172,6 +235,7 @@ export declare class DayOfWeekClient {
     getSchema(): Promise<any>;
     private get;
     private post;
+    private put;
     private patch;
     private delete;
     private request;

package/dist/client.js

@@ -8,6 +8,15 @@ import { basename, dirname, join } from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 const DEFAULT_BASE_URL = "https://field.dayofweek.com/app/api/dcli";
+/**
+ * Node's Buffer is a Uint8Array view over a possibly-larger, possibly-shared
+ * backing store, which is not assignable to BodyInit. Copy out the exact bytes.
+ */
+export function toArrayBuffer(view) {
+    const out = new ArrayBuffer(view.byteLength);
+    new Uint8Array(out).set(view);
+    return out;
+}
 export class ApiError extends Error {
     status;
     code;
@@ -279,6 +288,88 @@ export class DayOfWeekClient {
         const qs = params.toString();
         return this.get(`/admin/proposals${qs ? `?${qs}` : ""}`);
     }
+    // ── Knowledge ─────────────────────────────────────────────────────────────
+    /**
+     * List the knowledge documents attached to an entity. `full` returns each
+     * document's whole content instead of an excerpt, which is what you want when
+     * mirroring an entity's sources into an external knowledge base.
+     */
+    async listKnowledge(opts) {
+        const params = new URLSearchParams({ entity: opts.entity });
+        if (opts.full)
+            params.set("full", "1");
+        if (opts.org)
+            params.set("org", opts.org);
+        return this.get(`/knowledge?${params.toString()}`);
+    }
+    async getKnowledge(documentId, org) {
+        const params = new URLSearchParams({ document: documentId });
+        if (org)
+            params.set("org", org);
+        return this.get(`/knowledge?${params.toString()}`);
+    }
+    /** Semantic search across knowledge documents. */
+    async searchKnowledge(opts) {
+        const params = new URLSearchParams({ q: opts.query });
+        if (opts.entity)
+            params.set("entity", opts.entity);
+        if (opts.types?.length)
+            params.set("types", opts.types.join(","));
+        if (opts.limit)
+            params.set("limit", String(opts.limit));
+        if (opts.allOrgs)
+            params.set("allOrgs", "1");
+        if (opts.org)
+            params.set("org", opts.org);
+        return this.get(`/knowledge?${params.toString()}`);
+    }
+    /**
+     * Add a markdown knowledge note.
+     *
+     * Without `direct` this submits a proposal for human review — the default,
+     * and the only option non-admin tokens have. With `direct: true` an admin
+     * token writes the document immediately, skipping review. Ask the operator
+     * before doing that; see references/admin.md in the served skill.
+     */
+    async addKnowledge(input) {
+        return this.post("/knowledge", input);
+    }
+    /**
+     * Attach a binary source (PDF, DOCX, XLSX, …) to an entity. Admin only.
+     *
+     * Three hops: ask for an upload URL, send the bytes straight to Convex
+     * storage, then register the resulting storageId. The bytes never pass
+     * through function arguments, so file size isn't bounded by an arg limit.
+     */
+    async attachKnowledgeFile(input) {
+        const { uploadUrl } = await this.post("/knowledge/file", {
+            entityId: input.entityId,
+            org: input.org,
+        });
+        const byteSize = input.data.byteLength;
+        const uploadRes = await fetch(uploadUrl, {
+            method: "POST",
+            headers: { "Content-Type": input.mimeType },
+            body: input.data,
+        });
+        if (!uploadRes.ok) {
+            throw new ApiError(uploadRes.status, `Upload to storage failed: ${uploadRes.status} ${uploadRes.statusText}`);
+        }
+        const uploaded = (await uploadRes.json());
+        if (!uploaded.storageId)
+            throw new Error("Storage upload returned no storageId");
+        return this.put("/knowledge/file", {
+            entityId: input.entityId,
+            org: input.org,
+            storageId: uploaded.storageId,
+            fileName: input.fileName,
+            mimeType: input.mimeType,
+            byteSize,
+            sourceType: input.sourceType,
+            sourceUrl: input.sourceUrl,
+            sourceDescription: input.sourceDescription,
+        });
+    }
     // ── Skill ─────────────────────────────────────────────────────────────────
     async getSkillBundle(name) {
         return this.get(`/skill${name ? `?name=${encodeURIComponent(name)}` : ""}`);
@@ -297,6 +388,9 @@ export class DayOfWeekClient {
     async post(path, body) {
         return this.request(path, { method: "POST", body: JSON.stringify(body) });
     }
+    async put(path, body) {
+        return this.request(path, { method: "PUT", body: JSON.stringify(body) });
+    }
     async patch(path, body) {
         return this.request(path, { method: "PATCH", body: JSON.stringify(body) });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dayofweek/dcli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "CLI for the Day of Week AgTech platform — read data and submit proposals for review",
   "license": "MIT",
   "type": "module",