@dayofweek/dcli 1.3.0 → 1.5.0

package/README.md

@@ -1,91 +1,144 @@
 # @dayofweek/dcli
 
-CLI for the [Day of Week](https://dayofweek.com) AgTech platform.
+`dcli` is the Day of Week command-line client for personal and shared knowledge. It gives Agent Skills a narrow, auditable interface to shared notes and original sources without putting credentials or shared content inside your personal wiki.
 
-Read your organization's data and submit proposals for human review — nothing changes until you approve it.
+The Day of Week desktop app is the recommended installer. A signed standalone binary is also available for technical users; npm is required only when developing `dcli` itself.
 
-## Install
+## Sign in
 
 ```bash
-npm install -g @dayofweek/dcli
+dcli auth login --scopes brain:read,brain:write
+dcli auth status --json
+dcli doctor --json
 ```
 
-## Quick start
+Login uses a short-lived, single-use browser authorization code with PKCE. The device credential is stored in macOS Keychain, a Linux secret-service provider, Windows' protected credential file, or a permission-restricted file fallback. `dcli` does not write a new plaintext token to its JSON config.
+
+You can remove the device credential at any time:
 
 ```bash
-# Authenticate
-dcli auth set-token <your-token>
+dcli auth logout --json
+```
 
-# Browse your entities
-dcli read entities --json
+## Shared knowledge
 
-# Submit a proposal
-dcli agent propose --op create --table hierarchyEntities \
-  --title "New Farm" --source "my-agent" \
-  --parent <parentEntityId> --entity-type Farm \
-  --file payload.json
+```bash
+# Discover spaces that this device may access
+dcli brain list --json
+
+# Search one space
+dcli brain search "soil health" --area <areaId> --json
+
+# Read a canonical Day of Week URI
+dcli brain get 'dayofweek://brain/<areaId>/note/<noteId>' --json
 
-# Check proposal status
-dcli agent proposals --status pending
+# Explicitly share a local Markdown note
+dcli brain share --area <areaId> --title "Soil plan" \
+  --file wiki/soil-plan.md --intent interactive --json
+
+# Optimistic update; a stale version exits with the conflict exit code
+dcli brain update 'dayofweek://brain/<areaId>/note/<noteId>' \
+  --file wiki/soil-plan.md --if-version 3 --json
 ```
 
-## Agent integration
+Autonomous note creation is saved as a draft. Interactive creation is saved as approved. An organization role, Studio role, or administrator role never grants shared-space access on its own: access requires an active device scope and an active membership in the exact destination space.
+
+### Original files
+
+Original files are deliberately separate from note text:
 
 ```bash
-# Install the Agent Skill for AI agents
-dcli skill install
+dcli brain source upload --area <areaId> --file research.pdf --mime application/pdf --json
+dcli brain source get 'dayofweek://brain/<areaId>/source/<sourceId>' --json
+dcli brain source download 'dayofweek://brain/<areaId>/source/<sourceId>' \
+  --output ./downloads/research.pdf --json
+```
 
-# Works with OpenClaw, Claude Code, Cursor, VS Code Copilot,
-# Gemini CLI, Goose, OpenHands, and 25+ others
+Downloads require an explicit output path, verify SHA-256 while streaming, fsync the temporary file, and install it atomically. Existing destinations are not replaced unless `--overwrite` is supplied. Recorded meetings also require `--meeting --consent-ack`; that flag is an explicit attestation that participants were informed and consented.
+
+## Agent Skills
+
+Named bundles are deterministic and available to authenticated devices:
+
+```bash
+dcli skill list --json
+dcli skill install personal-llm-wiki --dir .agents/skills/personal-llm-wiki --json
+dcli skill install dayofweek-brain --dir .agents/skills/dayofweek-brain --json
+dcli skill status dayofweek-brain --dir .agents/skills/dayofweek-brain --json
+dcli skill update dayofweek-brain --dir .agents/skills/dayofweek-brain --json
 ```
 
-The skill follows the open [Agent Skills](https://agentskills.io) standard. After `dcli skill install`, any compatible agent on the machine discovers it automatically.
+Updates overwrite only files whose installed hash still matches the managed manifest. Locally edited managed files are preserved and the new server version is written beside them as `<name>.new`.
 
-## Commands
+The legacy entity/proposal Agent Skill remains available through `dcli skill install` without a bundle name.
 
-### Authentication
-- `dcli auth login` — Authenticate via browser
-- `dcli auth set-token <token>` — Save a token locally
-- `dcli auth status` — Check token health
-- `dcli auth devices` — List your agent tokens
-- `dcli auth create-token <name>` — Create an agent token
-- `dcli auth revoke <id>` — Revoke a token
+## URI contract
 
-### Reading data
-- `dcli read entities [--type Farm] [--parent <id>] [--limit 50]`
-- `dcli read entity <entityId>`
-- `dcli read produce [--entity <id>]`
-- `dcli read contacts [--entity <id>]`
+`dcli` accepts only exact canonical resource forms:
 
-### Proposals
-- `dcli agent propose --op create --table <table> --title <title> [--file payload.json]`
-- `dcli agent propose-batch --label <label> --file batch.json`
-- `dcli agent proposals [--status pending]`
-- `dcli agent show <proposalId>`
+```text
+dayofweek://brain/<areaId>/note/<noteId>
+dayofweek://brain/<areaId>/source/<sourceId>
+https://field.dayofweek.com/brain/<areaId>/note/<noteId>
+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.
 
-### Agent Skill
-- `dcli skill install` — Download skill (requires auth)
-- `dcli skill update` — Update to latest
-- `dcli skill status` — Check installed version
+```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
 
-## Configuration
+# Add a markdown note — submitted for human review
+dcli knowledge add --entity <entityId> --title "Variety catalogue" --file note.md
 
-dcli stores its config at `~/.config/dayofweek/dcli.json`.
+# Mirror an entity's sources to disk as markdown with provenance front-matter
+dcli knowledge export --entity <entityId> --out ./knowledge
+```
 
-Environment variables:
-- `DCLI_AUTH_TOKEN` — Auth token (overrides stored token)
-- `DCLI_API_URL` — Custom API base URL
+`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.
 
-## REST API
+## Legacy platform commands
 
-dcli talks to the Day of Week platform via a REST API. You can also call it directly:
+Existing read/proposal workflows remain compatible:
 
 ```bash
-curl -H "Authorization: Bearer dsk_xxx" \
-  "https://field.dayofweek.com/app/api/dcli/entities?type=Farm"
+dcli read entities --json
+dcli agent propose --op create --table hierarchyEntities \
+  --title "New Farm" --source "my-agent" \
+  --parent <parentEntityId> --entity-type Farm --file payload.json
+dcli agent proposals --status pending --json
 ```
 
-See the [API schema](https://field.dayofweek.com/app/api/dcli/schema) for all endpoints.
+## Configuration and development
+
+Non-secret preferences are stored at `~/.config/dayofweek/dcli.json`.
+
+- `DCLI_API_URL` overrides the API base URL.
+- `DCLI_AUTH_TOKEN` and `--token` remain temporary compatibility overrides; they are not persisted by the current login flow.
+
+Development commands:
+
+```bash
+npm install
+npm test
+npm run build
+npm run standalone:build
+npm run standalone:smoke
+```
 
 ## License
 

package/dist/auth/login.d.ts

@@ -0,0 +1,18 @@
+import { type LoopbackListener } from "./loopback.js";
+type LoginDependencies = {
+    startListener: () => Promise<LoopbackListener>;
+    openBrowser: (url: string) => Promise<unknown>;
+    fetch: typeof globalThis.fetch;
+};
+export declare function browserLogin(options: {
+    apiUrl: string;
+    scopes: string[];
+    deviceName?: string;
+    sourceApp?: "dcli" | "dayofweek-desktop";
+    dependencies?: Partial<LoginDependencies>;
+}): Promise<{
+    secret: string;
+    scopes: string[];
+    bootstrap: unknown;
+}>;
+export {};

package/dist/auth/login.js

@@ -0,0 +1,47 @@
+import { hostname } from "node:os";
+import { createAuthorizationRequest, verifyAuthorizationCallback } from "./pkce.js";
+import { startLoopbackListener } from "./loopback.js";
+export async function browserLogin(options) {
+    const dependencies = {
+        startListener: startLoopbackListener,
+        openBrowser: async (url) => (await import("open")).default(url),
+        fetch: globalThis.fetch,
+        ...options.dependencies,
+    };
+    const listener = await dependencies.startListener();
+    try {
+        const appBase = options.apiUrl.replace(/\/api\/dcli\/?$/, "");
+        const request = await createAuthorizationRequest({
+            authorizeUrl: `${appBase}/dcli/auth`,
+            redirectUri: listener.redirectUri,
+            deviceName: options.deviceName ?? hostname(),
+            scopes: options.scopes,
+        });
+        const authorizeUrl = new URL(request.url);
+        authorizeUrl.searchParams.set("source_app", options.sourceApp ?? "dcli");
+        await dependencies.openBrowser(authorizeUrl.toString());
+        const callbackUrl = await listener.waitForCallback();
+        const { code } = verifyAuthorizationCallback(callbackUrl, request.state);
+        const exchange = await dependencies.fetch(`${options.apiUrl}/auth/exchange`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ code, verifier: request.verifier, redirectUri: listener.redirectUri }),
+        });
+        if (!exchange.ok)
+            throw new Error("Authorization code exchange failed");
+        const credential = await exchange.json();
+        const bootstrapResponse = await dependencies.fetch(`${options.apiUrl}/brain/bootstrap`, {
+            headers: { Authorization: `Bearer ${credential.secret}` },
+        });
+        if (!bootstrapResponse.ok)
+            throw new Error("Day of Week bootstrap check failed");
+        return {
+            secret: credential.secret,
+            scopes: credential.scopes,
+            bootstrap: await bootstrapResponse.json(),
+        };
+    }
+    finally {
+        await listener.close();
+    }
+}

package/dist/auth/loopback.d.ts

@@ -0,0 +1,6 @@
+export type LoopbackListener = {
+    redirectUri: string;
+    waitForCallback(timeoutMs?: number): Promise<string>;
+    close(): Promise<void>;
+};
+export declare function startLoopbackListener(): Promise<LoopbackListener>;

package/dist/auth/loopback.js

@@ -0,0 +1,59 @@
+import { createServer } from "node:http";
+export async function startLoopbackListener() {
+    let callbackResolve;
+    let callbackReject;
+    const callback = new Promise((resolve, reject) => {
+        callbackResolve = resolve;
+        callbackReject = reject;
+    });
+    let settled = false;
+    const server = createServer((request, response) => {
+        const address = server.address();
+        const port = address && typeof address === "object" ? address.port : 0;
+        const url = new URL(request.url ?? "/", `http://127.0.0.1:${port}`);
+        response.statusCode = url.pathname === "/callback" ? 200 : 404;
+        response.setHeader("Content-Type", "text/plain; charset=utf-8");
+        response.setHeader("Cache-Control", "no-store");
+        response.setHeader("X-Content-Type-Options", "nosniff");
+        response.end(url.pathname === "/callback" ? "Day of Week authorization received. You can close this window." : "Not found");
+        if (!settled && url.pathname === "/callback") {
+            settled = true;
+            callbackResolve?.(url.toString());
+        }
+    });
+    server.on("error", (error) => {
+        if (!settled) {
+            settled = true;
+            callbackReject?.(error);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.listen(0, "127.0.0.1", resolve);
+        server.once("error", reject);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Could not bind loopback listener");
+    const redirectUri = `http://127.0.0.1:${address.port}/callback`;
+    return {
+        redirectUri,
+        async waitForCallback(timeoutMs = 120_000) {
+            let timer;
+            try {
+                return await Promise.race([
+                    callback,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("Authorization callback timed out")), timeoutMs);
+                    }),
+                ]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        },
+        async close() {
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,14 @@
+export declare function validateLoopbackRedirect(input: string): URL;
+export declare function createAuthorizationRequest(options: {
+    authorizeUrl: string;
+    redirectUri: string;
+    deviceName: string;
+    scopes: string[];
+}): Promise<{
+    url: string;
+    state: string;
+    verifier: string;
+}>;
+export declare function verifyAuthorizationCallback(callbackUrl: string, expectedState: string): {
+    code: string;
+};

package/dist/auth/pkce.js

@@ -0,0 +1,87 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+const ALLOWED_SCOPES = new Set(["brain:read", "brain:write", "brain:manage"]);
+function base64url(value) {
+    return Buffer.from(value).toString("base64url");
+}
+function safeEqual(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export function validateLoopbackRedirect(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new Error("Invalid loopback redirect URI");
+    }
+    if (url.protocol !== "http:" ||
+        url.hostname !== "127.0.0.1" ||
+        !url.port ||
+        url.pathname !== "/callback" ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new Error("Redirect must be an exact http://127.0.0.1:<port>/callback URI");
+    }
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+        throw new Error("Invalid loopback callback port");
+    }
+    return url;
+}
+export async function createAuthorizationRequest(options) {
+    const redirectUri = validateLoopbackRedirect(options.redirectUri).toString();
+    const scopes = [...new Set(options.scopes)];
+    if (scopes.length === 0 || scopes.some((scope) => !ALLOWED_SCOPES.has(scope))) {
+        throw new Error("Invalid requested brain scopes");
+    }
+    const deviceName = options.deviceName.trim();
+    if (!deviceName || deviceName.length > 100)
+        throw new Error("Invalid device name");
+    const state = base64url(randomBytes(32));
+    const verifier = base64url(randomBytes(48));
+    const challenge = createHash("sha256").update(verifier, "ascii").digest("base64url");
+    const url = new URL(options.authorizeUrl);
+    if (url.protocol !== "https:" && url.hostname !== "127.0.0.1") {
+        throw new Error("Authorization URL must use HTTPS");
+    }
+    url.search = new URLSearchParams({
+        redirect_uri: redirectUri,
+        state,
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        device_name: deviceName,
+        scope: scopes.join(" "),
+    }).toString();
+    return { url: url.toString(), state, verifier };
+}
+export function verifyAuthorizationCallback(callbackUrl, expectedState) {
+    const url = new URL(callbackUrl);
+    if (url.protocol !== "http:" ||
+        url.hostname !== "127.0.0.1" ||
+        url.pathname !== "/callback" ||
+        url.username ||
+        url.password ||
+        url.hash) {
+        throw new Error("Invalid authorization callback");
+    }
+    const keys = [...url.searchParams.keys()];
+    if (keys.length !== 2 ||
+        new Set(keys).size !== 2 ||
+        !keys.includes("code") ||
+        !keys.includes("state") ||
+        url.searchParams.getAll("code").length !== 1 ||
+        url.searchParams.getAll("state").length !== 1) {
+        throw new Error("Authorization callback must contain only code and state");
+    }
+    const code = url.searchParams.get("code") ?? "";
+    const state = url.searchParams.get("state") ?? "";
+    if (!/^[A-Za-z0-9_-]{3,256}$/.test(code))
+        throw new Error("Invalid authorization code");
+    if (!safeEqual(state, expectedState))
+        throw new Error("Authorization state mismatch");
+    return { code };
+}