@wardby/cli 0.2.1 → 0.4.0

package/dist/knowledge/concept.js

@@ -0,0 +1,78 @@
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+export const DEFAULT_KNOWLEDGE_BUNDLE_PATH = "docs/knowledge";
+export const RESERVED_BUNDLE_FILES = new Set(["index.md", "log.md"]);
+const CitationSchema = z.object({
+    id: z.string().min(1).optional(),
+    repo: z.string().min(1),
+    path: z
+        .string()
+        .min(1)
+        .refine((p) => !p.startsWith("/") && !p.split("/").includes(".."), "path must be repo-relative"),
+    lines: z
+        .tuple([z.number().int().min(1), z.number().int().min(1)])
+        .refine(([a, b]) => b >= a, "lines must be [start, end] with end >= start")
+        .optional(),
+    symbol: z.string().min(1).optional(),
+    sha: z.string().regex(/^[0-9a-f]{40}$/, "sha must be a full 40-hex commit"),
+    spanHash: z.string().regex(/^sha256:[0-9a-f]{64}$/, "spanHash must be sha256:<64 hex>"),
+});
+const WardbyBlockSchema = z
+    .object({
+    schema: z.literal(1),
+    roles: z.array(z.enum(["builder", "reviewer", "planner"])).default([]),
+    affects: z.array(z.string().min(1)).default([]),
+    citations: z.array(CitationSchema).default([]),
+    supersedes: z.string().nullable().optional(),
+    confidence: z.enum(["low", "medium", "high"]).optional(),
+})
+    .passthrough();
+const FrontMatterSchema = z
+    .object({
+    type: z.string().trim().min(1),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    status: z.enum(["draft", "stable", "deprecated"]).default("stable"),
+    wardby: WardbyBlockSchema.optional(),
+})
+    .passthrough();
+export function splitFrontMatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+    return match ? { yaml: match[1], body: match[2] } : null;
+}
+export function parseConcept(path, text) {
+    const base = path.split("/").pop() ?? path;
+    if (RESERVED_BUNDLE_FILES.has(base))
+        return { ok: false, error: `${base} is reserved and cannot be a concept` };
+    const split = splitFrontMatter(text);
+    if (!split)
+        return { ok: false, error: "missing YAML front-matter (--- ... ---)" };
+    let raw;
+    try {
+        raw = parseYaml(split.yaml);
+    }
+    catch (error) {
+        return { ok: false, error: `invalid YAML: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const parsed = FrontMatterSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        return { ok: false, error: `${issue.path.join(".") || "front-matter"}: ${issue.message}` };
+    }
+    const fm = parsed.data;
+    return {
+        ok: true,
+        concept: {
+            path,
+            type: fm.type,
+            title: fm.title,
+            description: fm.description,
+            status: fm.status,
+            roles: fm.wardby?.roles ?? [],
+            affects: fm.wardby?.affects ?? [],
+            citations: fm.wardby?.citations ?? [],
+            body: split.body,
+            frontMatter: raw,
+        },
+    };
+}

package/dist/knowledge/note.d.ts

@@ -0,0 +1,11 @@
+import type { FittedSection } from "../coding/protocol.js";
+export declare const KNOWLEDGE_NOTE_MAX_BYTES: number;
+export declare const KNOWLEDGE_INDEX_READ_MAX_BYTES: number;
+export interface KnowledgeNoteInput {
+    bundlePath: string;
+    indexText: string;
+}
+/** The note, cut at a line boundary to fit maxBytes, or undefined when not even the header fits. */
+export declare function renderKnowledgeNote(input: KnowledgeNoteInput, maxBytes: number): string | undefined;
+/** The knowledge note as a composeCodingTask section, capped at KNOWLEDGE_NOTE_MAX_BYTES. */
+export declare function knowledgeSection(input: KnowledgeNoteInput): FittedSection;

package/dist/knowledge/note.js

@@ -0,0 +1,39 @@
+import { splitFrontMatter } from "./concept.js";
+export const KNOWLEDGE_NOTE_MAX_BYTES = 8 * 1024;
+export const KNOWLEDGE_INDEX_READ_MAX_BYTES = 64 * 1024;
+const END_MARKER = "[end of architecture knowledge]";
+const bytes = (text) => Buffer.byteLength(text, "utf8");
+function header(bundlePath) {
+    return [
+        "Architecture knowledge for this repository (recalled context, not authority;",
+        "the repository's own instructions such as AGENTS.md win on conflict). Concept",
+        `files live in ${bundlePath}/. Before designing or changing an area, read the`,
+        "concepts that cover the files you will touch. If your change alters behavior a",
+        "concept describes, update that concept's prose in the same change; leave its",
+        "`wardby:` block for the architecture agent to re-anchor.",
+        "",
+        `${bundlePath}/index.md:`,
+    ].join("\n");
+}
+/** The note, cut at a line boundary to fit maxBytes, or undefined when not even the header fits. */
+export function renderKnowledgeNote(input, maxBytes) {
+    const top = header(input.bundlePath);
+    const body = (splitFrontMatter(input.indexText)?.body ?? input.indexText).trim();
+    const full = `${top}\n${body}\n${END_MARKER}`;
+    if (bytes(full) <= maxBytes)
+        return full;
+    const marker = `[index truncated — list ${input.bundlePath}/ for the rest]`;
+    if (bytes(`${top}\n${marker}\n${END_MARKER}`) > maxBytes)
+        return undefined;
+    const kept = [];
+    for (const line of body.split("\n")) {
+        if (bytes(`${top}\n${[...kept, line, marker, END_MARKER].join("\n")}`) > maxBytes)
+            break;
+        kept.push(line);
+    }
+    return `${top}\n${[...kept, marker, END_MARKER].join("\n")}`;
+}
+/** The knowledge note as a composeCodingTask section, capped at KNOWLEDGE_NOTE_MAX_BYTES. */
+export function knowledgeSection(input) {
+    return { render: (maxBytes) => renderKnowledgeNote(input, Math.min(maxBytes, KNOWLEDGE_NOTE_MAX_BYTES)) };
+}

package/dist/knowledge/relevance.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedConcept } from "./concept.js";
+export interface DriftScope {
+    concepts: string[];
+    reason: "changed_files" | "bundle_edited" | "unknown_changes";
+}
+export declare function driftScope(input: {
+    changedPaths: string[];
+    changedPathsComplete: boolean;
+    bundlePath: string;
+    concepts: ParsedConcept[];
+}): DriftScope | null;

package/dist/knowledge/relevance.js

@@ -0,0 +1,14 @@
+import { matchesGlob } from "../core/glob.js";
+export function driftScope(input) {
+    const all = input.concepts.map((c) => c.path).sort();
+    if (!input.changedPathsComplete)
+        return all.length ? { concepts: all, reason: "unknown_changes" } : null;
+    const prefix = `${input.bundlePath}/`;
+    const bundleEdited = input.changedPaths.some((p) => p.startsWith(prefix));
+    const selected = input.concepts.filter((concept) => input.changedPaths.some((changed) => changed === prefix + concept.path ||
+        concept.citations.some((c) => c.path === changed) ||
+        concept.affects.some((glob) => matchesGlob(changed, glob))));
+    if (!selected.length)
+        return null;
+    return { concepts: selected.map((c) => c.path).sort(), reason: bundleEdited ? "bundle_edited" : "changed_files" };
+}

package/dist/knowledge/span-hash.d.ts

@@ -0,0 +1,3 @@
+/** sha256 of lines A..B (1-based, inclusive), each followed by "\n"
+ * (equals `sed -n 'A,Bp' FILE | sha256sum` when the last cited line ends with a newline). */
+export declare function spanHash(fileText: string, lines?: [number, number]): string | null;

package/dist/knowledge/span-hash.js

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+/** sha256 of lines A..B (1-based, inclusive), each followed by "\n"
+ * (equals `sed -n 'A,Bp' FILE | sha256sum` when the last cited line ends with a newline). */
+export function spanHash(fileText, lines) {
+    const digest = (text) => `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+    if (!lines)
+        return digest(fileText);
+    const [start, end] = lines;
+    const all = fileText.endsWith("\n") ? fileText.slice(0, -1).split("\n") : fileText.split("\n");
+    if (start < 1 || end < start || end > all.length)
+        return null;
+    return digest(all
+        .slice(start - 1, end)
+        .map((line) => `${line}\n`)
+        .join(""));
+}

package/dist/mcp/auth/access.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The MCP seam for agent access (resource-sharing grants spec §3.3). Every
+ * agent tool routes through here instead of ownership.ts's owner-or-public
+ * rule, which no longer applies to agents: an owner-less agent is reachable
+ * only through its grants (the migration gives everyone execute).
+ *
+ * - Below read: 404 with the same text as a missing row, so existence never
+ *   leaks. At read or above but below the level required: 403 naming both.
+ * - The helpers take a `db` argument so a Serializable transaction reads the
+ *   grant rows through `tx`; a concurrent revoke then conflicts instead of
+ *   racing.
+ * - `ctx.operator` (stdio's local operator, never an HTTP principal) is
+ *   owner of every agent for access checks and sees every agent in
+ *   listings, but does NOT bypass requireBindingOwner: one owner's secrets,
+ *   datastores and repositories never reach another owner's agent.
+ */
+import type { Prisma, PrismaClient } from "#prisma";
+import { type Access, type Level } from "../../core/grants.js";
+import type { McpRequestContext } from "../context.js";
+import { McpError } from "../errors.js";
+export type AgentLevel = Level<"agent">;
+export type AgentAccess = Access<"agent">;
+type AgentRef = {
+    id: string;
+    ownerId: string | null;
+};
+type GrantDb = Pick<PrismaClient, "resourceGrant">;
+export declare function agentNotFound(id: string): McpError;
+export declare function insufficientAgentAccess(id: string, required: AgentLevel | "owner", held: AgentAccess): McpError;
+/** The caller's access to an agent row already read. */
+export declare function agentAccess(ctx: McpRequestContext, agent: AgentRef, db?: GrantDb): Promise<AgentAccess>;
+/** For a row already read (inside a transaction, or with includes): 404 below read, 403 below `required`. */
+export declare function assertAgentAccess<A extends AgentRef>(ctx: McpRequestContext, agent: A | null, id: string, required: AgentLevel | "owner", db?: GrantDb): Promise<{
+    agent: A;
+    access: AgentAccess;
+}>;
+/** 404 if missing or access < read; 403 if read <= access < required. Returns row + access. */
+export declare function requireAgentAccess(ctx: McpRequestContext, id: string, required: AgentLevel | "owner", db?: Pick<PrismaClient, "agent" | "resourceGrant">): Promise<{
+    agent: {
+        name: string;
+        model: string;
+        budgetUsd: import("@prisma/client-runtime-utils").Decimal;
+        createdAt: Date;
+        updatedAt: Date;
+        kind: import("#prisma").AgentKind;
+        id: string;
+        ownerId: string | null;
+        systemPrompt: string;
+        schedule: string | null;
+        timezone: string;
+        scheduleEnabled: boolean;
+        lastScheduledAt: Date | null;
+        maxTurns: number;
+        defectProjectKey: string | null;
+        defectIssueType: string | null;
+        budgetGroupId: string | null;
+        memoryEnabled: boolean;
+        effort: string | null;
+    };
+    access: AgentAccess;
+}>;
+/**
+ * Bindings (secrets, datastores, repositories, capability grants): strict
+ * ownership, whatever the grants. The stdio operator does NOT bypass this:
+ * it can adopt the agent first (make_owner / grants adopt-public).
+ */
+export declare function requireBindingOwner(ctx: McpRequestContext, agent: AgentRef): void;
+/** Prisma where for agent listings: own rows plus rows granted >= read; the operator sees all. */
+export declare function readableAgentsWhere(ctx: McpRequestContext, db?: GrantDb): Promise<Prisma.AgentWhereInput>;
+/** One grant lookup for a whole listing: returns agent -> the caller's access. */
+export declare function agentAccessResolver(ctx: McpRequestContext, db?: GrantDb): Promise<(agent: AgentRef) => AgentAccess>;
+export {};

package/dist/mcp/auth/access.js

@@ -0,0 +1,58 @@
+import { atLeast, effectiveAccess, grantedAccessMap, grantedIds } from "../../core/grants.js";
+import { McpError } from "../errors.js";
+export function agentNotFound(id) {
+    return new McpError(404, `Agent "${id}" not found.`);
+}
+function describeLevel(level) {
+    return level === "owner" ? "the agent's owner" : `${level} access`;
+}
+export function insufficientAgentAccess(id, required, held) {
+    return new McpError(403, `Agent "${id}": this needs ${describeLevel(required)}; you have ${held === "owner" ? "owner" : held} access.`);
+}
+/** The caller's access to an agent row already read. */
+export function agentAccess(ctx, agent, db = ctx.db) {
+    return effectiveAccess(db, "agent", agent, ctx.principal.id, { operator: ctx.operator === true });
+}
+/** For a row already read (inside a transaction, or with includes): 404 below read, 403 below `required`. */
+export async function assertAgentAccess(ctx, agent, id, required, db = ctx.db) {
+    if (!agent)
+        throw agentNotFound(id);
+    const access = await agentAccess(ctx, agent, db);
+    if (!atLeast("agent", access, "read"))
+        throw agentNotFound(id);
+    if (!atLeast("agent", access, required))
+        throw insufficientAgentAccess(id, required, access);
+    return { agent, access };
+}
+/** 404 if missing or access < read; 403 if read <= access < required. Returns row + access. */
+export async function requireAgentAccess(ctx, id, required, db = ctx.db) {
+    const agent = await db.agent.findUnique({ where: { id } });
+    return assertAgentAccess(ctx, agent, id, required, db);
+}
+/**
+ * Bindings (secrets, datastores, repositories, capability grants): strict
+ * ownership, whatever the grants. The stdio operator does NOT bypass this:
+ * it can adopt the agent first (make_owner / grants adopt-public).
+ */
+export function requireBindingOwner(ctx, agent) {
+    if (agent.ownerId === null) {
+        throw new McpError(403, `Agent "${agent.id}" has no owner, so nothing can be bound to it; an admin can assign one with make_owner.`);
+    }
+    if (agent.ownerId !== ctx.principal.id) {
+        throw new McpError(403, `Only the owner of agent "${agent.id}" can change its bindings.`);
+    }
+}
+/** Prisma where for agent listings: own rows plus rows granted >= read; the operator sees all. */
+export async function readableAgentsWhere(ctx, db = ctx.db) {
+    if (ctx.operator)
+        return {};
+    const ids = await grantedIds(db, "agent", ctx.principal.id, "read");
+    return { OR: [{ ownerId: ctx.principal.id }, { id: { in: ids } }] };
+}
+/** One grant lookup for a whole listing: returns agent -> the caller's access. */
+export async function agentAccessResolver(ctx, db = ctx.db) {
+    if (ctx.operator)
+        return () => "owner";
+    const granted = await grantedAccessMap(db, "agent", ctx.principal.id);
+    return (agent) => agent.ownerId !== null && agent.ownerId === ctx.principal.id ? "owner" : (granted.get(agent.id) ?? "none");
+}

package/dist/mcp/auth/grants-cli.d.ts

@@ -0,0 +1,149 @@
+import { type PrismaClient } from "#prisma";
+/** The report needs only raw queries, so it can run on a schema the generated client doesn't match. */
+export interface ReportDb {
+    $queryRaw<T = unknown>(query: TemplateStringsArray, ...values: unknown[]): PromiseLike<T>;
+}
+export declare const BEHAVIOUR_CHANGES: string[];
+export interface MigrationReport {
+    grantsTable: boolean;
+    ownerlessAgents: {
+        agentId: string;
+        name: string;
+        everyoneGrant: string | null;
+        /** What adopting the agent as each principal would bring back into force (review I3). */
+        revivedByAdopter: {
+            principalId: string;
+            subject: string;
+            secrets: string[];
+            datastores: string[];
+            toolCapabilities: string[];
+        }[];
+    }[];
+    inertBindings: {
+        kind: "secret" | "datastore";
+        agentId: string;
+        agentName: string;
+        agentOwnerId: string | null;
+        boundName: string;
+        resourceId: string;
+        resourceOwnerId: string | null;
+        /** Removed by prune-bindings (owned agent); on an owner-less agent adopt-public decides. */
+        prunable: boolean;
+    }[];
+    suspendedCapabilities: {
+        agentId: string;
+        agentName: string;
+        toolId: string;
+        toolName: string;
+        regrant: string;
+    }[];
+    /**
+     * Capabilities the migration stamps with the current owner on owner-less
+     * tools: a previous owner may have set them before a make_owner (review
+     * M2). They stay in force; the owner should review them.
+     */
+    reviewCapabilities: {
+        agentId: string;
+        agentName: string;
+        toolId: string;
+        toolName: string;
+        regrant: string;
+    }[];
+    failingEdges: {
+        parentAgentId: string;
+        parentOwnerId: string | null;
+        childAgentId: string;
+        childOwnerId: string | null;
+        boundName: string;
+    }[];
+    webhooks: {
+        onOwnerlessAgents: {
+            id: string;
+            agentId: string;
+            createdBy: string | null;
+        }[];
+        creatorLacksExecute: {
+            id: string;
+            agentId: string;
+            createdBy: string | null;
+        }[];
+    };
+    behaviourChanges: string[];
+    orphanGrants: {
+        id: string;
+        resourceType: string;
+        resourceId: string;
+    }[] | null;
+}
+export declare function migrationReport(db: ReportDb): Promise<MigrationReport>;
+export declare function formatMigrationReport(report: MigrationReport): string;
+export interface AdoptedAgent {
+    agentId: string;
+    name: string;
+    bindingsRemoved: {
+        kind: "secret" | "datastore";
+        boundName: string;
+        resourceId: string;
+    }[];
+    bindingsKept: {
+        kind: "secret" | "datastore";
+        boundName: string;
+    }[];
+    capabilitiesStamped: string[];
+    /** Every attached tool the new owner doesn't own (review M7); `regrant` only when it had capabilities. */
+    foreignTools: {
+        toolId: string;
+        toolName: string;
+        toolOwnerId: string | null;
+        regrant: string | null;
+    }[];
+    failingEdges: {
+        parentAgentId: string;
+        childAgentId: string;
+        boundName: string;
+    }[];
+    /** The everyone grant before and after adoption (null = none). */
+    everyoneGrant: {
+        before: string | null;
+        after: string | null;
+    };
+}
+export interface AdoptResult {
+    owner: {
+        id: string;
+        subject: string;
+    };
+    dryRun: boolean;
+    agents: AdoptedAgent[];
+}
+/** Gives every owner-less agent `ownerSubject` as its owner. See the module header. */
+export declare function adoptPublic(db: PrismaClient, opts: {
+    ownerSubject: string;
+    dryRun: boolean;
+    keepEveryoneExecute?: boolean;
+}): Promise<AdoptResult>;
+export declare function formatAdoptResult(result: AdoptResult): string;
+export interface PruneResult {
+    dryRun: boolean;
+    removed: {
+        kind: "secret" | "datastore";
+        agentId: string;
+        agentName: string;
+        boundName: string;
+        resourceId: string;
+        resourceOwnerId: string | null;
+    }[];
+}
+/** Deletes cross-owner secret/datastore bindings on owned agents, in one transaction. */
+export declare function pruneBindings(db: PrismaClient, opts: {
+    dryRun: boolean;
+}): Promise<PruneResult>;
+export declare function formatPruneResult(result: PruneResult): string;
+/**
+ * The owner of an agent made with `wardby agent create` (resource-sharing
+ * grants spec §3.8): `--owner <subject>` must already exist (a typo never
+ * mints a principal), otherwise the local operator (LOCAL_PRINCIPAL),
+ * found or created exactly as stdio does.
+ */
+export declare function resolveCliAgentOwner(db: PrismaClient, ownerSubject: string | undefined, localPrincipal: string): Promise<string>;
+export declare function grantsCommand(args: string[], db: PrismaClient, output?: (value: string) => void): Promise<void>;