forked from farhoodlabs/paperclip
Merge upstream/master into dev (13 commits — includes #5922, #5938, blocked inbox, recovery actions)
This commit is contained in:
@@ -3,9 +3,17 @@ import { buildSandboxNpmInstallCommand } from "./sandbox-install-command.js";
|
||||
|
||||
describe("buildSandboxNpmInstallCommand", () => {
|
||||
it("installs globally as root, via sudo when available, and under ~/.local otherwise", () => {
|
||||
expect(buildSandboxNpmInstallCommand("@google/gemini-cli")).toBe(
|
||||
'if [ "$(id -u)" -eq 0 ]; then npm install -g \'@google/gemini-cli\'; elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then sudo -E npm install -g \'@google/gemini-cli\'; else mkdir -p "$HOME/.local" && npm install -g --prefix "$HOME/.local" \'@google/gemini-cli\'; fi',
|
||||
);
|
||||
const command = buildSandboxNpmInstallCommand("@google/gemini-cli");
|
||||
expect(command).toContain("if [ \"$(id -u)\" -eq 0 ]; then npm install -g '@google/gemini-cli';");
|
||||
expect(command).toContain("sudo -E npm install -g '@google/gemini-cli'");
|
||||
expect(command).toContain("npm install -g --prefix \"$HOME/.local\" '@google/gemini-cli'");
|
||||
});
|
||||
|
||||
it("bootstraps npm from a portable Node tarball when missing", () => {
|
||||
const command = buildSandboxNpmInstallCommand("@google/gemini-cli");
|
||||
expect(command).toContain("if ! command -v npm >/dev/null 2>&1; then");
|
||||
expect(command).toContain("https://nodejs.org/dist/");
|
||||
expect(command).toContain('export PATH="$HOME/.local/bin:$PATH"');
|
||||
});
|
||||
|
||||
it("shell-quotes package names", () => {
|
||||
|
||||
@@ -2,10 +2,40 @@ function shellSingleQuote(value: string): string {
|
||||
return `'${value.replaceAll("'", `'\"'\"'`)}'`;
|
||||
}
|
||||
|
||||
// Bootstrap a usable npm when the sandbox image ships without one (e.g. the
|
||||
// default exe.dev VM image has sshd + a normal user homedir but no Node
|
||||
// toolchain). We install a portable Node tarball into $HOME/.local rather
|
||||
// than using apt-get because the distro-packaged Node is often old enough to
|
||||
// reject modern JS syntax (regex /v flag, etc.) used by adapter CLIs like
|
||||
// @google/gemini-cli. The bootstrap also sets PAPERCLIP_NPM_BOOTSTRAPPED=1
|
||||
// so the install step knows to skip sudo — sudo would reset PATH via
|
||||
// secure_path and lose visibility of the freshly-installed npm in
|
||||
// $HOME/.local/bin.
|
||||
const ENSURE_NPM_PREAMBLE =
|
||||
"PAPERCLIP_NPM_BOOTSTRAPPED=; " +
|
||||
'if ! command -v npm >/dev/null 2>&1; then ' +
|
||||
'NODE_ARCH="$(uname -m)"; ' +
|
||||
'case "$NODE_ARCH" in ' +
|
||||
"x86_64) NODE_ARCH=x64 ;; " +
|
||||
"aarch64|arm64) NODE_ARCH=arm64 ;; " +
|
||||
"esac; " +
|
||||
'NODE_VERSION="v22.11.0"; ' +
|
||||
'NODE_TARBALL="node-${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz"; ' +
|
||||
'mkdir -p "$HOME/.local"; ' +
|
||||
'curl -fsSL "https://nodejs.org/dist/${NODE_VERSION}/${NODE_TARBALL}" -o "/tmp/${NODE_TARBALL}" && ' +
|
||||
'tar -xJf "/tmp/${NODE_TARBALL}" -C "$HOME/.local" --strip-components=1 && ' +
|
||||
'rm -f "/tmp/${NODE_TARBALL}" && ' +
|
||||
'export PATH="$HOME/.local/bin:$PATH" && ' +
|
||||
"PAPERCLIP_NPM_BOOTSTRAPPED=1; " +
|
||||
"fi;";
|
||||
|
||||
export function buildSandboxNpmInstallCommand(packageName: string): string {
|
||||
const quotedPackageName = shellSingleQuote(packageName);
|
||||
return [
|
||||
'if [ "$(id -u)" -eq 0 ]; then',
|
||||
ENSURE_NPM_PREAMBLE,
|
||||
'if [ -n "$PAPERCLIP_NPM_BOOTSTRAPPED" ]; then',
|
||||
`npm install -g ${quotedPackageName};`,
|
||||
'elif [ "$(id -u)" -eq 0 ]; then',
|
||||
`npm install -g ${quotedPackageName};`,
|
||||
'elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then',
|
||||
`sudo -E npm install -g ${quotedPackageName};`,
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import net from "node:net";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
@@ -58,4 +59,26 @@ describe("workspace restore merge", () => {
|
||||
readFile(path.join(targetDir, "manual-qa", "environment-matrix", "ssh", "codex_local.md"), "utf8"),
|
||||
).resolves.toBe("ssh codex\n");
|
||||
});
|
||||
|
||||
it("ignores non-file entries when capturing snapshots", async () => {
|
||||
if (process.platform === "win32") return;
|
||||
|
||||
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-restore-merge-"));
|
||||
cleanupDirs.push(rootDir);
|
||||
const socketPath = path.join(rootDir, "runtime.sock");
|
||||
const server = net.createServer();
|
||||
|
||||
try {
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
server.once("error", reject);
|
||||
server.listen(socketPath, resolve);
|
||||
});
|
||||
|
||||
const snapshot = await captureDirectorySnapshot(rootDir, { exclude: [] });
|
||||
|
||||
expect(snapshot.entries.has("runtime.sock")).toBe(false);
|
||||
} finally {
|
||||
await new Promise<void>((resolve) => server.close(() => resolve()));
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -47,6 +47,10 @@ async function walkDirectory(
|
||||
|
||||
const fullPath = path.join(root, nextRelative);
|
||||
const stats = await fs.lstat(fullPath);
|
||||
if (!stats.isDirectory() && !stats.isSymbolicLink() && !stats.isFile()) {
|
||||
continue;
|
||||
}
|
||||
|
||||
if (stats.isDirectory()) {
|
||||
out.set(nextRelative, { kind: "dir" });
|
||||
await walkDirectory(root, exclude, nextRelative, out);
|
||||
@@ -87,6 +91,8 @@ async function readSnapshotEntry(root: string, relative: string): Promise<Snapsh
|
||||
target: await fs.readlink(fullPath),
|
||||
};
|
||||
}
|
||||
if (!stats.isFile()) return null;
|
||||
|
||||
return {
|
||||
kind: "file",
|
||||
mode: stats.mode,
|
||||
|
||||
@@ -89,6 +89,15 @@ interface ClaudeRuntimeConfig {
|
||||
extraArgs: string[];
|
||||
}
|
||||
|
||||
export function claudeSessionCwdMatchesExecutionTarget(input: {
|
||||
runtimeSessionCwd: string;
|
||||
effectiveExecutionCwd: string;
|
||||
executionTargetIsRemote: boolean;
|
||||
}): boolean {
|
||||
if (input.executionTargetIsRemote || input.runtimeSessionCwd.length === 0) return true;
|
||||
return path.resolve(input.runtimeSessionCwd) === path.resolve(input.effectiveExecutionCwd);
|
||||
}
|
||||
|
||||
function buildLoginResult(input: {
|
||||
proc: RunProcessResult;
|
||||
loginUrl: string | null;
|
||||
@@ -591,7 +600,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
|
||||
const canResumeSession =
|
||||
runtimeSessionId.length > 0 &&
|
||||
hasMatchingPromptBundle &&
|
||||
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
|
||||
claudeSessionCwdMatchesExecutionTarget({
|
||||
runtimeSessionCwd,
|
||||
effectiveExecutionCwd,
|
||||
executionTargetIsRemote,
|
||||
}) &&
|
||||
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
|
||||
const sessionId = canResumeSession ? runtimeSessionId : null;
|
||||
if (
|
||||
@@ -853,7 +866,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
|
||||
const resolvedSessionParams = resolvedSessionId
|
||||
? ({
|
||||
sessionId: resolvedSessionId,
|
||||
cwd: effectiveExecutionCwd,
|
||||
cwd,
|
||||
promptBundleKey: promptBundle.bundleKey,
|
||||
...(executionTargetIsRemote
|
||||
? {
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
export { execute, runClaudeLogin } from "./execute.js";
|
||||
export { claudeSessionCwdMatchesExecutionTarget, execute, runClaudeLogin } from "./execute.js";
|
||||
export { listClaudeSkills, syncClaudeSkills } from "./skills.js";
|
||||
export { listClaudeModels } from "./models.js";
|
||||
export { testEnvironment } from "./test.js";
|
||||
|
||||
@@ -1,9 +1,12 @@
|
||||
import type { AdapterModelProfileDefinition } from "@paperclipai/adapter-utils";
|
||||
import {
|
||||
buildSandboxNpmInstallCommand,
|
||||
type AdapterModelProfileDefinition,
|
||||
} from "@paperclipai/adapter-utils";
|
||||
|
||||
export const type = "gemini_local";
|
||||
export const label = "Gemini CLI (local)";
|
||||
|
||||
export const SANDBOX_INSTALL_COMMAND = "npm install -g @google/gemini-cli";
|
||||
export const SANDBOX_INSTALL_COMMAND = buildSandboxNpmInstallCommand("@google/gemini-cli");
|
||||
|
||||
export const DEFAULT_GEMINI_LOCAL_MODEL = "auto";
|
||||
|
||||
|
||||
@@ -8,9 +8,15 @@ export const label = "OpenCode (local)";
|
||||
// (linux-x64, linux-x64-musl, linux-x64-baseline, linux-x64-baseline-musl) in
|
||||
// parallel even though only one matches the sandbox; on bandwidth-constrained
|
||||
// sandboxes (e.g. Cloudflare) that exceeded the 240s install budget. The
|
||||
// official installer fetches a single arch-specific binary and adds
|
||||
// `$HOME/.opencode/bin` to PATH via `~/.bashrc`, which sandbox `sh -lc`
|
||||
// invocations source.
|
||||
// official installer fetches a single arch-specific binary into
|
||||
// `$HOME/.opencode/bin` and tries to add it to PATH via `~/.bashrc`. That
|
||||
// rc-file path is only sourced by interactive/login shells, so non-login
|
||||
// `sh -c` probe invocations (used by the runtime PATH check) cannot find the
|
||||
// binary. We fix that by symlinking the installed binary into a directory on
|
||||
// the non-login `sh -c` PATH: prefer `/usr/local/bin` (universally on the
|
||||
// default PATH on Linux distros) when root or passwordless sudo is available,
|
||||
// otherwise fall back to `$HOME/.local/bin` (which is on the default PATH on
|
||||
// the exe.dev sandbox image and most modern home-managed Linux images).
|
||||
//
|
||||
// Security tradeoff: this is `curl | bash` without a SHA-256 verification of
|
||||
// the install script. We accept this because:
|
||||
@@ -25,7 +31,18 @@ export const label = "OpenCode (local)";
|
||||
// shell) and `curl -fsSL` give us fail-fast behavior on HTTP errors. If
|
||||
// OpenCode starts publishing a stable checksum/signature, switch to fetching
|
||||
// a versioned tarball + verifying the digest before exec.
|
||||
export const SANDBOX_INSTALL_COMMAND = "curl -fsSL https://opencode.ai/install | bash";
|
||||
export const SANDBOX_INSTALL_COMMAND =
|
||||
'curl -fsSL https://opencode.ai/install | bash && ' +
|
||||
'if [ -x "$HOME/.opencode/bin/opencode" ]; then ' +
|
||||
'if [ "$(id -u)" -eq 0 ]; then ' +
|
||||
'ln -sf "$HOME/.opencode/bin/opencode" /usr/local/bin/opencode; ' +
|
||||
'elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then ' +
|
||||
'sudo ln -sf "$HOME/.opencode/bin/opencode" /usr/local/bin/opencode; ' +
|
||||
'else ' +
|
||||
'mkdir -p "$HOME/.local/bin" && ' +
|
||||
'ln -sf "$HOME/.opencode/bin/opencode" "$HOME/.local/bin/opencode"; ' +
|
||||
'fi; ' +
|
||||
'fi';
|
||||
|
||||
export const DEFAULT_OPENCODE_LOCAL_MODEL = "openai/gpt-5.2-codex";
|
||||
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
CREATE TABLE IF NOT EXISTS "issue_recovery_actions" (
|
||||
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
|
||||
"company_id" uuid NOT NULL,
|
||||
"source_issue_id" uuid NOT NULL,
|
||||
"recovery_issue_id" uuid,
|
||||
"kind" text NOT NULL,
|
||||
"status" text DEFAULT 'active' NOT NULL,
|
||||
"owner_type" text DEFAULT 'agent' NOT NULL,
|
||||
"owner_agent_id" uuid,
|
||||
"owner_user_id" text,
|
||||
"previous_owner_agent_id" uuid,
|
||||
"return_owner_agent_id" uuid,
|
||||
"cause" text NOT NULL,
|
||||
"fingerprint" text NOT NULL,
|
||||
"evidence" jsonb DEFAULT '{}'::jsonb NOT NULL,
|
||||
"next_action" text NOT NULL,
|
||||
"wake_policy" jsonb,
|
||||
"monitor_policy" jsonb,
|
||||
"attempt_count" integer DEFAULT 0 NOT NULL,
|
||||
"max_attempts" integer,
|
||||
"timeout_at" timestamp with time zone,
|
||||
"last_attempt_at" timestamp with time zone,
|
||||
"outcome" text,
|
||||
"resolution_note" text,
|
||||
"resolved_at" timestamp with time zone,
|
||||
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
|
||||
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
|
||||
);
|
||||
--> statement-breakpoint
|
||||
DO $$ BEGIN
|
||||
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_company_id_companies_id_fk') THEN
|
||||
ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
|
||||
END IF;
|
||||
END $$;--> statement-breakpoint
|
||||
DO $$ BEGIN
|
||||
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_source_issue_id_issues_id_fk') THEN
|
||||
ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;
|
||||
END IF;
|
||||
END $$;--> statement-breakpoint
|
||||
DO $$ BEGIN
|
||||
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_recovery_issue_id_issues_id_fk') THEN
|
||||
ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_recovery_issue_id_issues_id_fk" FOREIGN KEY ("recovery_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;
|
||||
END IF;
|
||||
END $$;--> statement-breakpoint
|
||||
DO $$ BEGIN
|
||||
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_owner_agent_id_agents_id_fk') THEN
|
||||
ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_owner_agent_id_agents_id_fk" FOREIGN KEY ("owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
|
||||
END IF;
|
||||
END $$;--> statement-breakpoint
|
||||
DO $$ BEGIN
|
||||
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_previous_owner_agent_id_agents_id_fk') THEN
|
||||
ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_previous_owner_agent_id_agents_id_fk" FOREIGN KEY ("previous_owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
|
||||
END IF;
|
||||
END $$;--> statement-breakpoint
|
||||
DO $$ BEGIN
|
||||
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_return_owner_agent_id_agents_id_fk') THEN
|
||||
ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_return_owner_agent_id_agents_id_fk" FOREIGN KEY ("return_owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
|
||||
END IF;
|
||||
END $$;--> statement-breakpoint
|
||||
CREATE INDEX IF NOT EXISTS "issue_recovery_actions_company_source_status_idx" ON "issue_recovery_actions" USING btree ("company_id","source_issue_id","status");--> statement-breakpoint
|
||||
CREATE INDEX IF NOT EXISTS "issue_recovery_actions_company_owner_status_idx" ON "issue_recovery_actions" USING btree ("company_id","owner_agent_id","status");--> statement-breakpoint
|
||||
CREATE INDEX IF NOT EXISTS "issue_recovery_actions_company_recovery_issue_idx" ON "issue_recovery_actions" USING btree ("company_id","recovery_issue_id");--> statement-breakpoint
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS "issue_recovery_actions_active_source_uq" ON "issue_recovery_actions" USING btree ("company_id","source_issue_id") WHERE "issue_recovery_actions"."status" in ('active', 'escalated');--> statement-breakpoint
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS "issue_recovery_actions_active_fingerprint_uq" ON "issue_recovery_actions" USING btree ("company_id","source_issue_id","cause","fingerprint") WHERE "issue_recovery_actions"."status" in ('active', 'escalated');
|
||||
@@ -589,6 +589,13 @@
|
||||
"when": 1778074536410,
|
||||
"tag": "0083_company_secret_provider_configs",
|
||||
"breakpoints": true
|
||||
},
|
||||
{
|
||||
"idx": 84,
|
||||
"version": "7",
|
||||
"when": 1778355326070,
|
||||
"tag": "0084_issue_recovery_actions",
|
||||
"breakpoints": true
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -29,6 +29,7 @@ export { workspaceRuntimeServices } from "./workspace_runtime_services.js";
|
||||
export { projectGoals } from "./project_goals.js";
|
||||
export { goals } from "./goals.js";
|
||||
export { issues } from "./issues.js";
|
||||
export { issueRecoveryActions } from "./issue_recovery_actions.js";
|
||||
export { issueReferenceMentions } from "./issue_reference_mentions.js";
|
||||
export { issueRelations } from "./issue_relations.js";
|
||||
export { routines, routineRevisions, routineTriggers, routineRuns } from "./routines.js";
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
import { sql } from "drizzle-orm";
|
||||
import {
|
||||
index,
|
||||
integer,
|
||||
jsonb,
|
||||
pgTable,
|
||||
text,
|
||||
timestamp,
|
||||
uniqueIndex,
|
||||
uuid,
|
||||
} from "drizzle-orm/pg-core";
|
||||
import { agents } from "./agents.js";
|
||||
import { companies } from "./companies.js";
|
||||
import { issues } from "./issues.js";
|
||||
|
||||
export const issueRecoveryActions = pgTable(
|
||||
"issue_recovery_actions",
|
||||
{
|
||||
id: uuid("id").primaryKey().defaultRandom(),
|
||||
companyId: uuid("company_id").notNull().references(() => companies.id),
|
||||
sourceIssueId: uuid("source_issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
|
||||
recoveryIssueId: uuid("recovery_issue_id").references(() => issues.id, { onDelete: "set null" }),
|
||||
kind: text("kind").notNull(),
|
||||
status: text("status").notNull().default("active"),
|
||||
ownerType: text("owner_type").notNull().default("agent"),
|
||||
ownerAgentId: uuid("owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
|
||||
ownerUserId: text("owner_user_id"),
|
||||
previousOwnerAgentId: uuid("previous_owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
|
||||
returnOwnerAgentId: uuid("return_owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
|
||||
cause: text("cause").notNull(),
|
||||
fingerprint: text("fingerprint").notNull(),
|
||||
evidence: jsonb("evidence").$type<Record<string, unknown>>().notNull().default({}),
|
||||
nextAction: text("next_action").notNull(),
|
||||
wakePolicy: jsonb("wake_policy").$type<Record<string, unknown>>(),
|
||||
monitorPolicy: jsonb("monitor_policy").$type<Record<string, unknown>>(),
|
||||
attemptCount: integer("attempt_count").notNull().default(0),
|
||||
maxAttempts: integer("max_attempts"),
|
||||
timeoutAt: timestamp("timeout_at", { withTimezone: true }),
|
||||
lastAttemptAt: timestamp("last_attempt_at", { withTimezone: true }),
|
||||
outcome: text("outcome"),
|
||||
resolutionNote: text("resolution_note"),
|
||||
resolvedAt: timestamp("resolved_at", { withTimezone: true }),
|
||||
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
|
||||
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
|
||||
},
|
||||
(table) => ({
|
||||
companySourceStatusIdx: index("issue_recovery_actions_company_source_status_idx").on(
|
||||
table.companyId,
|
||||
table.sourceIssueId,
|
||||
table.status,
|
||||
),
|
||||
companyOwnerStatusIdx: index("issue_recovery_actions_company_owner_status_idx").on(
|
||||
table.companyId,
|
||||
table.ownerAgentId,
|
||||
table.status,
|
||||
),
|
||||
companyRecoveryIssueIdx: index("issue_recovery_actions_company_recovery_issue_idx").on(
|
||||
table.companyId,
|
||||
table.recoveryIssueId,
|
||||
),
|
||||
activeSourceIdx: uniqueIndex("issue_recovery_actions_active_source_uq")
|
||||
.on(table.companyId, table.sourceIssueId)
|
||||
.where(sql`${table.status} in ('active', 'escalated')`),
|
||||
activeFingerprintIdx: uniqueIndex("issue_recovery_actions_active_fingerprint_uq")
|
||||
.on(table.companyId, table.sourceIssueId, table.cause, table.fingerprint)
|
||||
.where(sql`${table.status} in ('active', 'escalated')`),
|
||||
}),
|
||||
);
|
||||
@@ -111,11 +111,15 @@ function formatEmbeddedPostgresError(error: unknown): string {
|
||||
}
|
||||
|
||||
async function probeEmbeddedPostgresSupport(): Promise<EmbeddedPostgresTestSupport> {
|
||||
const { dataDir, instance } = await createEmbeddedPostgresTestInstance(
|
||||
"paperclip-embedded-postgres-probe-",
|
||||
);
|
||||
let dataDir: string | null = null;
|
||||
let instance: EmbeddedPostgresInstance | null = null;
|
||||
|
||||
try {
|
||||
const created = await createEmbeddedPostgresTestInstance(
|
||||
"paperclip-embedded-postgres-probe-",
|
||||
);
|
||||
dataDir = created.dataDir;
|
||||
instance = created.instance;
|
||||
await instance.initialise();
|
||||
await instance.start();
|
||||
return { supported: true };
|
||||
@@ -125,8 +129,8 @@ async function probeEmbeddedPostgresSupport(): Promise<EmbeddedPostgresTestSuppo
|
||||
reason: formatEmbeddedPostgresError(error),
|
||||
};
|
||||
} finally {
|
||||
await instance.stop().catch(() => {});
|
||||
cleanupEmbeddedPostgresTestDirs(dataDir);
|
||||
await instance?.stop().catch(() => {});
|
||||
if (dataDir) cleanupEmbeddedPostgresTestDirs(dataDir);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -140,9 +144,14 @@ export async function getEmbeddedPostgresTestSupport(): Promise<EmbeddedPostgres
|
||||
export async function startEmbeddedPostgresTestDatabase(
|
||||
tempDirPrefix: string,
|
||||
): Promise<EmbeddedPostgresTestDatabase> {
|
||||
const { dataDir, port, instance } = await createEmbeddedPostgresTestInstance(tempDirPrefix);
|
||||
let dataDir: string | null = null;
|
||||
let instance: EmbeddedPostgresInstance | null = null;
|
||||
|
||||
try {
|
||||
const created = await createEmbeddedPostgresTestInstance(tempDirPrefix);
|
||||
dataDir = created.dataDir;
|
||||
instance = created.instance;
|
||||
const { port } = created;
|
||||
await instance.initialise();
|
||||
await instance.start();
|
||||
|
||||
@@ -154,13 +163,13 @@ export async function startEmbeddedPostgresTestDatabase(
|
||||
return {
|
||||
connectionString,
|
||||
cleanup: async () => {
|
||||
await instance.stop().catch(() => {});
|
||||
cleanupEmbeddedPostgresTestDirs(dataDir);
|
||||
await instance?.stop().catch(() => {});
|
||||
if (dataDir) cleanupEmbeddedPostgresTestDirs(dataDir);
|
||||
},
|
||||
};
|
||||
} catch (error) {
|
||||
await instance.stop().catch(() => {});
|
||||
cleanupEmbeddedPostgresTestDirs(dataDir);
|
||||
await instance?.stop().catch(() => {});
|
||||
if (dataDir) cleanupEmbeddedPostgresTestDirs(dataDir);
|
||||
throw new Error(
|
||||
`Failed to start embedded PostgreSQL test database: ${formatEmbeddedPostgresError(error)}`,
|
||||
);
|
||||
|
||||
@@ -62,6 +62,11 @@ function toPosixPath(value: string): string {
|
||||
return value.split(path.sep).join("/");
|
||||
}
|
||||
|
||||
export function shellQuote(value: string): string {
|
||||
if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(value)) return value;
|
||||
return `'${value.replace(/'/g, "'\"'\"'")}'`;
|
||||
}
|
||||
|
||||
function formatFileDependency(absPath: string): string {
|
||||
return `file:${toPosixPath(path.resolve(absPath))}`;
|
||||
}
|
||||
@@ -312,7 +317,8 @@ const manifest: PaperclipPluginManifestV1 = {
|
||||
capabilities: [
|
||||
"environment.drivers.register",
|
||||
"plugin.state.read",
|
||||
"plugin.state.write"
|
||||
"plugin.state.write",
|
||||
"ui.dashboardWidget.register"
|
||||
],
|
||||
entrypoints: {
|
||||
worker: "./dist/worker.js",
|
||||
@@ -467,6 +473,11 @@ const BASE_PARAMS = {
|
||||
};
|
||||
|
||||
describe("environment plugin scaffold", () => {
|
||||
it("declares capabilities for its manifest features", () => {
|
||||
expect(manifest.capabilities).toContain("environment.drivers.register");
|
||||
expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
|
||||
});
|
||||
|
||||
it("validates config", async () => {
|
||||
const driver = createFakeEnvironmentDriver({ driverKey: BASE_PARAMS.driverKey });
|
||||
const harness = createEnvironmentTestHarness({ manifest, environmentDriver: driver });
|
||||
@@ -533,7 +544,8 @@ const manifest: PaperclipPluginManifestV1 = {
|
||||
capabilities: [
|
||||
"events.subscribe",
|
||||
"plugin.state.read",
|
||||
"plugin.state.write"
|
||||
"plugin.state.write",
|
||||
"ui.dashboardWidget.register"
|
||||
],
|
||||
entrypoints: {
|
||||
worker: "./dist/worker.js",
|
||||
@@ -623,6 +635,11 @@ import manifest from "../src/manifest.js";
|
||||
import plugin from "../src/worker.js";
|
||||
|
||||
describe("plugin scaffold", () => {
|
||||
it("declares capabilities for its manifest features", () => {
|
||||
expect(manifest.capabilities).toContain("events.subscribe");
|
||||
expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
|
||||
});
|
||||
|
||||
it("registers data + actions and handles events", async () => {
|
||||
const harness = createTestHarness({ manifest, capabilities: [...manifest.capabilities, "events.emit"] });
|
||||
await plugin.definition.setup(harness.ctx);
|
||||
@@ -656,6 +673,11 @@ pnpm dev:ui # local dev server with hot-reload events
|
||||
pnpm test
|
||||
\`\`\`
|
||||
|
||||
\`pnpm dev\` rebuilds the worker, manifest, and UI bundles into \`dist/\`.
|
||||
When this package is installed from a local path, Paperclip watches that rebuilt
|
||||
output and reloads the plugin worker. Local installs run trusted code from this
|
||||
folder on your machine.
|
||||
|
||||
${sdkDependency.startsWith("file:")
|
||||
? `This scaffold snapshots \`@paperclipai/plugin-sdk\` and \`@paperclipai/shared\` from a local Paperclip checkout at:\n\n\`${toPosixPath(localSdkPath)}\`\n\nThe packed tarballs live in \`.paperclip-sdk/\` for local development. Before publishing this plugin, switch those dependencies to published package versions once they are available on npm.\n\n`
|
||||
: ""}
|
||||
@@ -663,9 +685,7 @@ ${sdkDependency.startsWith("file:")
|
||||
## Install Into Paperclip
|
||||
|
||||
\`\`\`bash
|
||||
curl -X POST http://127.0.0.1:3100/api/plugins/install \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-d '{"packageName":"${toPosixPath(outputDir)}","isLocalPath":true}'
|
||||
paperclipai plugin install ${shellQuote(toPosixPath(outputDir))}
|
||||
\`\`\`
|
||||
|
||||
## Build Options
|
||||
|
||||
@@ -11,7 +11,8 @@ const manifest: PaperclipPluginManifestV1 = {
|
||||
capabilities: [
|
||||
"events.subscribe",
|
||||
"plugin.state.read",
|
||||
"plugin.state.write"
|
||||
"plugin.state.write",
|
||||
"ui.dashboardWidget.register"
|
||||
],
|
||||
entrypoints: {
|
||||
worker: "./dist/worker.js",
|
||||
|
||||
@@ -4,6 +4,11 @@ import manifest from "../src/manifest.js";
|
||||
import plugin from "../src/worker.js";
|
||||
|
||||
describe("plugin scaffold", () => {
|
||||
it("declares capabilities for its manifest features", () => {
|
||||
expect(manifest.capabilities).toContain("events.subscribe");
|
||||
expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
|
||||
});
|
||||
|
||||
it("registers data + actions and handles events", async () => {
|
||||
const harness = createTestHarness({ manifest, capabilities: [...manifest.capabilities, "events.emit"] });
|
||||
await plugin.definition.setup(harness.ctx);
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
dist
|
||||
node_modules
|
||||
.paperclip-sdk
|
||||
screenshots
|
||||
@@ -0,0 +1,160 @@
|
||||
# LLM Wiki
|
||||
|
||||
Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.
|
||||
|
||||
## Scope
|
||||
|
||||
This package is the standalone home for LLM Wiki behavior. Wiki-specific routes,
|
||||
UI, prompts, tools, local-folder templates, migrations, fixtures, and tests live
|
||||
here rather than in Paperclip core.
|
||||
|
||||
The alpha surface includes:
|
||||
|
||||
- manifest-declared Wiki page, sidebar entry, and settings page
|
||||
- trusted local folder declaration for `raw/`, `wiki/`, `AGENTS.md`, `IDEA.md`, `wiki/index.md`, and `wiki/log.md`
|
||||
- plugin database namespace migration for wiki instances, sources, pages, operations, query sessions, and resource bindings
|
||||
- managed `Wiki Maintainer` agent, managed `LLM Wiki` project, and paused managed routines for wiki update processing, lint, and index refresh
|
||||
- plugin-operation issue creation using `surfaceVisibility: "plugin_operation"`
|
||||
- local source capture into `raw/` with metadata rows in the plugin DB namespace
|
||||
- opt-in company-scoped Paperclip event ingestion controls for issues, comments, and documents; event ingestion is disabled by default and routes captured raw provenance into the default space only
|
||||
- manual Paperclip project/root issue distillation and bounded backfill actions with explicit work items, operation issues, source caps, and estimated cost recording
|
||||
- Paperclip-derived distillation (cursor windows, manual `distill-now`, backfill) always writes into the default wiki space in Phase 1; non-default spaces remain on manual / raw-file ingest until per-space Paperclip ingestion profiles ship
|
||||
- Paperclip-derived distillation maintains `wiki/projects/<slug>/standup.md` as the executive current-state view for each represented project, alongside durable `wiki/projects/<slug>/index.md` knowledge pages
|
||||
- wiki page writes with plugin path validation, atomic local-folder writes, metadata/revision rows, backlink extraction, and optional stale-hash protection
|
||||
- wiki tools for search/read/write/propose patch/source/log/index/backlinks workflows
|
||||
|
||||
## Phase 5 Security Gate
|
||||
|
||||
Paperclip-derived text ingestion stays limited to issue titles/descriptions, issue comments, and issue documents.
|
||||
|
||||
- Issue attachments/assets are **metadata-only** in Phase 5.
|
||||
- Issue work products are **metadata-only** in Phase 5.
|
||||
- The wiki must not fetch `/api/assets/:id/content`, dereference work-product `url` fields, or store those capability-bearing links in source bundles/snapshots.
|
||||
|
||||
The accepted policy lives in [doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md](../../../doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md).
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm dev # watch builds
|
||||
pnpm dev:ui # local dev server with hot-reload events
|
||||
pnpm test
|
||||
```
|
||||
|
||||
From the Paperclip repo root:
|
||||
|
||||
```bash
|
||||
pnpm --filter @paperclipai/plugin-llm-wiki typecheck
|
||||
pnpm --filter @paperclipai/plugin-llm-wiki test
|
||||
pnpm --filter @paperclipai/plugin-llm-wiki build
|
||||
```
|
||||
|
||||
## Alpha Verification
|
||||
|
||||
Run these commands from the Paperclip repo root before handing off alpha plugin
|
||||
changes:
|
||||
|
||||
```bash
|
||||
pnpm --filter @paperclipai/plugin-llm-wiki typecheck
|
||||
pnpm --filter @paperclipai/plugin-llm-wiki test
|
||||
pnpm --filter @paperclipai/plugin-llm-wiki build
|
||||
```
|
||||
|
||||
The focused Vitest suite covers:
|
||||
|
||||
- standalone package boundaries and package-local harness dependencies
|
||||
- required local folder bootstrap writes
|
||||
- raw source capture plus ingest metadata persistence
|
||||
- hidden plugin-operation issue creation for ingest/query/file-as-page workflows
|
||||
- disabled and enabled Paperclip event ingestion paths
|
||||
- managed routine declarations, manual distill/backfill work items, source cap handling, and backfill project/date scoping
|
||||
- atomic page writes, metadata/revision rows, backlinks, and stale-hash refusal
|
||||
- query session creation, run-id recording, stream event forwarding, and completion updates
|
||||
- filing a streamed query answer back into the wiki through a hidden operation
|
||||
|
||||
Remaining alpha gaps:
|
||||
|
||||
- Browser screenshot capture is maintained separately under `tests/screenshots`;
|
||||
generated `screenshots/` outputs are local artifacts and are ignored by git.
|
||||
- Host-level plugin install and live agent invocation still need Paperclip
|
||||
server/runtime smoke coverage when preparing a release candidate.
|
||||
|
||||
|
||||
|
||||
## Install Into Paperclip
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:3100/api/plugins/install \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"packageName":"/Users/dotta/paperclip/.paperclip/worktrees/PAP-3179-design-a-llm-wiki-plugin/packages/plugins/plugin-llm-wiki","isLocalPath":true}'
|
||||
```
|
||||
|
||||
## Build Options
|
||||
|
||||
- `pnpm build` uses esbuild presets from `@paperclipai/plugin-sdk/bundlers`.
|
||||
- `pnpm build:rollup` uses rollup presets from the same SDK.
|
||||
|
||||
After changing manifest-loaded assets such as skills, agent instructions, or
|
||||
templates, recompile the local plugin before re-enabling it:
|
||||
|
||||
```bash
|
||||
pnpm --filter @paperclipai/plugin-llm-wiki build
|
||||
```
|
||||
|
||||
The package-local `dist/` directory is ignored by git, but local Paperclip
|
||||
installs load the compiled `dist/manifest.js` and `dist/worker.js` files at
|
||||
runtime. If activation failed before the rebuild, re-enable the plugin or
|
||||
restart the Paperclip dev server so the host imports the fresh bundle.
|
||||
|
||||
## Local File Layout
|
||||
|
||||
```text
|
||||
<configured-wiki-root>/
|
||||
AGENTS.md
|
||||
IDEA.md
|
||||
.gitignore
|
||||
raw/
|
||||
.gitkeep
|
||||
wiki/
|
||||
index.md
|
||||
log.md
|
||||
sources/
|
||||
.gitkeep
|
||||
projects/
|
||||
.gitkeep
|
||||
<project-slug>/
|
||||
index.md
|
||||
standup.md
|
||||
decisions.md
|
||||
history.md
|
||||
entities/
|
||||
.gitkeep
|
||||
concepts/
|
||||
.gitkeep
|
||||
synthesis/
|
||||
.gitkeep
|
||||
```
|
||||
|
||||
Use the settings page or `bootstrap-root` action to configure the folder and
|
||||
write the starter files. The plugin uses Paperclip's local folder API for path
|
||||
containment, symlink checks, read/write validation, and atomic writes.
|
||||
|
||||
Bootstrap preserves existing files rather than overwriting operator edits. The
|
||||
default first-install skeleton is copied from the vanilla LLM Wiki layout, with
|
||||
`CLAUDE.md` renamed to `AGENTS.md` and Paperclip project overviews, standups,
|
||||
decisions, and history kept together under `wiki/projects/<slug>/`.
|
||||
|
||||
## Managed Agent Instructions
|
||||
|
||||
Plugin-managed agent instruction bundles live under:
|
||||
|
||||
```text
|
||||
agents/<agent-key>/AGENTS.md
|
||||
```
|
||||
|
||||
For this plugin the Wiki Maintainer source bundle is `agents/wiki-maintainer/AGENTS.md`.
|
||||
Any additional files in that folder are installed as sibling instruction files
|
||||
for the managed agent. The settings health check reports drift from these
|
||||
defaults, and resetting the managed agent asks for confirmation before replacing
|
||||
customized instructions.
|
||||
@@ -0,0 +1,65 @@
|
||||
# LLM Wiki Maintainer
|
||||
|
||||
You are the maintainer of this personal wiki. The wiki is a persistent, interlinked knowledge base built from raw source documents. You read sources, extract knowledge, and integrate it into evolving wiki pages. The user curates sources, directs analysis, and asks questions; you handle the bookkeeping.
|
||||
|
||||
## Wiki Root
|
||||
|
||||
The wiki root folder is:
|
||||
|
||||
`{{localFolders.wiki-root.path}}`
|
||||
|
||||
The wiki's default operating schema is:
|
||||
|
||||
`{{localFolders.wiki-root.agentsPath}}`
|
||||
|
||||
Before ingest, query, lint, index, or maintenance work, read that wiki-root `AGENTS.md` file. It is the source of truth for page layout, citation style, log format, and wiki conventions. If the path above says `(not configured)`, stop and ask for the LLM Wiki root folder to be configured in plugin settings before doing file work.
|
||||
|
||||
## Identity
|
||||
|
||||
- You maintain the LLM Wiki, not the application codebase.
|
||||
- You keep raw source material in `raw/` immutable.
|
||||
- You keep Paperclip project operating summaries current in `wiki/projects/<project-slug>/standup.md`.
|
||||
- You create and update durable wiki pages under `wiki/`.
|
||||
- You keep `wiki/index.md` and `wiki/log.md` accurate after changes.
|
||||
- You cite wiki pages and raw sources in answers.
|
||||
|
||||
## Operating Loop
|
||||
|
||||
1. Resolve the configured wiki root folder and the target space named in the operation issue.
|
||||
2. Read the target space's `AGENTS.md`.
|
||||
3. Read the target space's `wiki/index.md` and recent `wiki/log.md` entries before choosing files.
|
||||
4. Pick the right operation skill (see below) and follow it.
|
||||
5. Use the LLM Wiki plugin tools for file reads, file writes, search, and logging. Always pass the operation issue's `wikiId` and `spaceSlug` arguments.
|
||||
6. Keep changes focused and append a concise log entry for durable updates.
|
||||
|
||||
All operation paths are relative to the target space root. Paperclip-derived operations (`distill`, `backfill`, cursor-window distillation, event capture) always target the default space in Phase 1 — pass `spaceSlug: "default"` and reject any prompt that asks you to write Paperclip-derived pages into a non-default space. Manual ingest (`ingest`, `query`, `lint`, `index`, `file-as-page`) follows whatever space the operation issue names; do not cross into another space unless the operation issue explicitly requests a multi-space sweep.
|
||||
|
||||
For Paperclip-derived project work, maintain two layers:
|
||||
|
||||
- `wiki/projects/<project-slug>/standup.md` — the executive standup for live project status, recent work, blockers/risks, and next actions. Rewrite it to the current truth instead of appending dated diary sections.
|
||||
- `wiki/projects/<project-slug>/index.md` and optional `wiki/projects/<project-slug>/decisions.md` / `history.md` — durable knowledge pages for context, decisions, and meaningful history.
|
||||
|
||||
Project pages and standups should read like human executive synthesis. Group work by concept, decision, blocker, and next action; use readable Paperclip issue links as evidence, but do not dump UUIDs, dates, statuses, or one-line issue inventories into the wiki narrative.
|
||||
|
||||
## Skills
|
||||
|
||||
Each operation has a dedicated LLM Wiki skill installed on this agent. Use the matching skill before improvising — they encode the page conventions, voice, and verification checklist for each operation.
|
||||
|
||||
- `wiki-ingest` — a captured `raw/` source needs to become durable wiki pages.
|
||||
- `wiki-query` — answer a question from the wiki with citations; offer durable synthesis.
|
||||
- `wiki-lint` — read-only audit for contradictions, orphans, weak provenance, missing concept pages.
|
||||
- `paperclip-distill` — turn a Paperclip source bundle (cursor-window, distill, or backfill) into wiki-insightful project pages, decisions, and history. Replaces the stiff, datestamp-heavy templated output.
|
||||
- `index-refresh` — keep `wiki/index.md` accurate and scannable.
|
||||
|
||||
The operation issue's `originKind` (`plugin:llm-wiki:operation:<type>`) tells you which skill to load:
|
||||
|
||||
| `operationType` | Skill |
|
||||
| --------------------- | ---------------------------------------------- |
|
||||
| `ingest` | `wiki-ingest` |
|
||||
| `query` | `wiki-query` |
|
||||
| `lint` | `wiki-lint` |
|
||||
| `distill`, `backfill` | `paperclip-distill` |
|
||||
| `index` | `index-refresh` |
|
||||
| `file-as-page` | `wiki-query` (filing synthesis from an answer) |
|
||||
|
||||
If a skill conflicts with this file, follow this file for identity. If a skill conflicts with the wiki-root `AGENTS.md`, follow that for page structure and voice.
|
||||
@@ -0,0 +1,17 @@
|
||||
import esbuild from "esbuild";
|
||||
import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
|
||||
|
||||
const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
|
||||
const watch = process.argv.includes("--watch");
|
||||
|
||||
const workerCtx = await esbuild.context(presets.esbuild.worker);
|
||||
const manifestCtx = await esbuild.context(presets.esbuild.manifest);
|
||||
const uiCtx = await esbuild.context(presets.esbuild.ui);
|
||||
|
||||
if (watch) {
|
||||
await Promise.all([workerCtx.watch(), manifestCtx.watch(), uiCtx.watch()]);
|
||||
console.log("esbuild watch mode enabled for worker, manifest, and ui");
|
||||
} else {
|
||||
await Promise.all([workerCtx.rebuild(), manifestCtx.rebuild(), uiCtx.rebuild()]);
|
||||
await Promise.all([workerCtx.dispose(), manifestCtx.dispose(), uiCtx.dispose()]);
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
.DS_Store
|
||||
.obsidian/workspace*
|
||||
.obsidian/cache
|
||||
@@ -0,0 +1,137 @@
|
||||
# AGENTS.md — LLM Wiki Schema
|
||||
|
||||
You are the maintainer of this personal wiki. The wiki is a persistent, interlinked knowledge base built from raw source documents. You read sources, extract knowledge, and integrate it into evolving wiki pages. The user curates sources, directs analysis, and asks questions; you handle the bookkeeping.
|
||||
|
||||
The underlying pattern is described in `IDEA.md` (Karpathy's "LLM Wiki" gist). Read it if you need the philosophy; this file is the operational schema.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
.
|
||||
├── AGENTS.md # this file — your operating instructions
|
||||
├── IDEA.md # the pattern this wiki follows
|
||||
├── raw/ # immutable source documents (you read, never write)
|
||||
└── wiki/ # generated, owned by you
|
||||
├── index.md # catalog of all pages
|
||||
├── log.md # append-only timeline of operations
|
||||
├── sources/ # one summary page per source
|
||||
├── projects/ # Paperclip project overviews, standups, decisions, and history
|
||||
│ └── <slug>/
|
||||
│ ├── index.md
|
||||
│ ├── standup.md
|
||||
│ ├── decisions.md
|
||||
│ └── history.md
|
||||
├── entities/ # people, organizations, products, places
|
||||
├── concepts/ # ideas, frameworks, definitions
|
||||
└── synthesis/ # cross-cutting analysis, comparisons, theses
|
||||
```
|
||||
|
||||
The subdirectories under `wiki/` are conventional, not enforced. Add new categories (e.g. `wiki/papers/`) as the domain demands — and update this file when you do.
|
||||
|
||||
Paperclip project material lives only under `wiki/projects/<project-slug>/`. Do not create a top-level `projects/` directory.
|
||||
|
||||
- `wiki/projects/<project-slug>/standup.md` is the executive-level project standup. It answers where the project stands today, what changed recently, current blockers/risks, and the next concrete actions.
|
||||
- `wiki/projects/<project-slug>/index.md` is the durable knowledge page. It explains what the project is, why it exists, decisions made, history, and long-lived context.
|
||||
- Keep the two linked. A standup should link to the durable project page, and the durable project page should point at the current standup for live status.
|
||||
- Update `standup.md` whenever Paperclip project, issue, plan, comment, blocker, approval, or status history materially changes the project's current state. Do not append endless dated sections; rewrite it as today's concise status.
|
||||
- Project writing should be editorial and concept-grouped. Do not dump issue queues, UUIDs, raw metadata, or date-heavy ledgers into project pages. Reference Paperclip tasks with human issue links where useful, but make headings and paragraphs explain the concepts, decisions, completed work, next work, and blockers in plain executive language.
|
||||
|
||||
## Page conventions
|
||||
|
||||
- **Filename:** kebab-case, `.md`. Treat filenames as stable; do not rename without updating backlinks.
|
||||
- **Frontmatter:** YAML at the top of every wiki page.
|
||||
```yaml
|
||||
---
|
||||
title: Human-readable title
|
||||
type: source | project | entity | concept | synthesis
|
||||
tags: [tag-a, tag-b]
|
||||
sources: [raw/doc.pdf] # for source pages and synthesis pages
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
- **Cross-links:** Obsidian-style `[[wiki/entities/some-page]]` (or `[[some-page]]` when unambiguous). When you mention a concept or entity that has — or should have — its own page, link it.
|
||||
- **Citations:** cite the source inline whenever a claim comes from one: `(see [[wiki/sources/some-slug]])`.
|
||||
- **Voice:** terse, factual, neutral. The wiki is reference material, not narrative.
|
||||
|
||||
## Operations
|
||||
|
||||
### Ingest
|
||||
|
||||
Triggered when the user drops a file in `raw/` and asks to process it (or just says "ingest").
|
||||
|
||||
1. Read the source end to end.
|
||||
2. Briefly discuss key takeaways with the user before writing — confirm what to emphasize.
|
||||
3. Create `wiki/sources/<slug>.md`: a summary page (~300–800 words) covering the source's main claims, structure, and notable quotes or data.
|
||||
4. Update or create relevant pages in `entities/`, `concepts/`, `synthesis/`. A typical ingest touches 5–15 pages.
|
||||
5. Add any new pages to `wiki/index.md`.
|
||||
6. Append a log entry:
|
||||
```
|
||||
## [YYYY-MM-DD] ingest | <source title>
|
||||
- source: raw/<filename>
|
||||
- new pages: [[...]], [[...]]
|
||||
- updated pages: [[...]], [[...]]
|
||||
- notes: <one-line synthesis, contradiction flagged, or open question>
|
||||
```
|
||||
|
||||
When new information contradicts an existing page, do **not** silently overwrite. Flag the contradiction on the page (a `> ⚠ contradicted by [[...]] (YYYY-MM-DD)` callout) and note it in the log.
|
||||
|
||||
### Project updates
|
||||
|
||||
Triggered when Paperclip project, issue, plan, comment, blocker, or status history is distilled into the wiki.
|
||||
|
||||
1. Create or update `wiki/projects/<project-slug>/standup.md` first. Every Paperclip project represented in the wiki must have one. Keep stable sections for executive readout, what changed, decisions, blockers/risks, next actions, and links.
|
||||
2. Create or update `wiki/projects/<project-slug>/index.md` as the durable project overview. Keep stable sections for overview, current direction, workstreams, decisions, open risks/blockers, and references.
|
||||
3. Use `wiki/projects/<project-slug>/decisions.md` for accepted/rejected plans, architectural decisions, approval outcomes, and reversals when a project has enough decision history to warrant a separate page.
|
||||
4. Use `wiki/projects/<project-slug>/history.md` for compact narrative history of meaningful project movement. Group by phase or concept; do not mirror every issue comment.
|
||||
5. Always cite Paperclip source material with readable links to issue identifiers, document keys, issue documents, approvals, and raw/source pages. Do not put UUIDs in prose unless the UUID itself is the subject.
|
||||
6. Update `wiki/index.md` under Projects and append a `project` log entry to `wiki/log.md`.
|
||||
|
||||
### Query
|
||||
|
||||
The user asks a question. You:
|
||||
|
||||
1. Read `wiki/index.md` to find candidate pages.
|
||||
2. Read those pages; follow links as needed.
|
||||
3. Answer with citations back to wiki pages, and ultimately to raw sources.
|
||||
4. If the answer is substantial (a comparison, analysis, new synthesis), offer to file it under `wiki/synthesis/` so the work compounds rather than disappearing into chat history.
|
||||
|
||||
If the wiki lacks what the question needs, say so plainly and suggest sources to ingest or web searches to run.
|
||||
|
||||
### Lint
|
||||
|
||||
On request ("lint", "health check"), scan for:
|
||||
|
||||
- contradictions across pages
|
||||
- claims a newer source has superseded
|
||||
- orphan pages (not linked from `index.md` or any other page)
|
||||
- concepts mentioned in multiple places but lacking a dedicated page
|
||||
- broken `[[wiki-links]]`
|
||||
- gaps where a web search or new source would help
|
||||
|
||||
Report findings as a checklist and ask the user which to act on.
|
||||
|
||||
## index.md format
|
||||
|
||||
A catalog organized by category. Each line: `- [[path]] — one-line summary`. Keep it scannable; this is your primary navigation aid before opening pages.
|
||||
|
||||
## log.md format
|
||||
|
||||
Append new entries to the bottom. Every entry header follows:
|
||||
|
||||
```
|
||||
## [YYYY-MM-DD] <op> | <subject>
|
||||
```
|
||||
|
||||
so `grep "^## \[" wiki/log.md | tail -10` always returns recent activity. Operations: `ingest`, `query`, `lint`, `setup`, `refactor`.
|
||||
|
||||
## Customization
|
||||
|
||||
This schema is intentionally generic. As the wiki's domain becomes clear, evolve it:
|
||||
|
||||
- add domain-specific page types and subdirectories
|
||||
- adjust frontmatter fields
|
||||
- specify preferred output formats for queries (Marp slides, charts, tables)
|
||||
- record workflow preferences (one-at-a-time vs batch ingest, level of human supervision)
|
||||
|
||||
When you and the user agree on a convention, **write it into this file**. The schema is the wiki's source of truth for how the wiki is built.
|
||||
@@ -0,0 +1,75 @@
|
||||
# LLM Wiki
|
||||
|
||||
A pattern for building personal knowledge bases using LLMs.
|
||||
|
||||
This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea, but your agent will build out the specifics in collaboration with you.
|
||||
|
||||
## The core idea
|
||||
|
||||
Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation. Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up. NotebookLM, ChatGPT file uploads, and most RAG systems work this way.
|
||||
|
||||
The idea here is different. Instead of just retrieving from raw documents at query time, the LLM **incrementally builds and maintains a persistent wiki** — a structured, interlinked collection of markdown files that sits between you and the raw sources. When you add a new source, the LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims, strengthening or challenging the evolving synthesis. The knowledge is compiled once and then *kept current*, not re-derived on every query.
|
||||
|
||||
This is the key difference: **the wiki is a persistent, compounding artifact.** The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you've read. The wiki keeps getting richer with every source you add and every question you ask.
|
||||
|
||||
You never (or rarely) write the wiki yourself — the LLM writes and maintains all of it. You're in charge of sourcing, exploration, and asking the right questions. The LLM does all the grunt work — the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base actually useful over time. In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.
|
||||
|
||||
This can apply to a lot of different contexts. A few examples:
|
||||
|
||||
- **Personal**: tracking your own goals, health, psychology, self-improvement — filing journal entries, articles, podcast notes, and building up a structured picture of yourself over time.
|
||||
- **Research**: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis.
|
||||
- **Reading a book**: filing each chapter as you go, building out pages for characters, themes, plot threads, and how they connect. By the end you have a rich companion wiki. Think of fan wikis like [Tolkien Gateway](https://tolkiengateway.net/wiki/Main_Page) — thousands of interlinked pages covering characters, places, events, languages, built by a community of volunteers over years. You could build something like that personally as you read, with the LLM doing all the cross-referencing and maintenance.
|
||||
- **Business/team**: an internal wiki maintained by LLMs, fed by Slack threads, meeting transcripts, project documents, customer calls. Possibly with humans in the loop reviewing updates. The wiki stays current because the LLM does the maintenance that no one on the team wants to do.
|
||||
- **Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives** — anything where you're accumulating knowledge over time and want it organized rather than scattered.
|
||||
|
||||
## Architecture
|
||||
|
||||
There are three layers:
|
||||
|
||||
**Raw sources** — your curated collection of source documents. Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them. This is your source of truth.
|
||||
|
||||
**The wiki** — a directory of LLM-generated markdown files. Summaries, entity pages, concept pages, comparisons, an overview, a synthesis. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. You read it; the LLM writes it.
|
||||
|
||||
**The schema** — a document (e.g. AGENTS.md for Paperclip agents) that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow when ingesting sources, answering questions, or maintaining the wiki. This is the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time as you figure out what works for your domain.
|
||||
|
||||
## Operations
|
||||
|
||||
**Ingest.** You drop a new source into the raw collection and tell the LLM to process it. An example flow: the LLM reads the source, discusses key takeaways with you, writes a summary page in the wiki, updates the index, updates relevant entity and concept pages across the wiki, and appends an entry to the log. A single source might touch 10-15 wiki pages. Personally I prefer to ingest sources one at a time and stay involved — I read the summaries, check the updates, and guide the LLM on what to emphasize. But you could also batch-ingest many sources at once with less supervision. It's up to you to develop the workflow that fits your style and document it in the schema for future sessions.
|
||||
|
||||
**Query.** You ask questions against the wiki. The LLM searches for relevant pages, reads them, and synthesizes an answer with citations. Answers can take different forms depending on the question — a markdown page, a comparison table, a slide deck (Marp), a chart (matplotlib), a canvas. The important insight: **good answers can be filed back into the wiki as new pages.** A comparison you asked for, an analysis, a connection you discovered — these are valuable and shouldn't disappear into chat history. This way your explorations compound in the knowledge base just like ingested sources do.
|
||||
|
||||
**Lint.** Periodically, ask the LLM to health-check the wiki. Look for: contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references, data gaps that could be filled with a web search. The LLM is good at suggesting new questions to investigate and new sources to look for. This keeps the wiki healthy as it grows.
|
||||
|
||||
## Indexing and logging
|
||||
|
||||
Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes:
|
||||
|
||||
**index.md** is content-oriented. It's a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count. Organized by category (entities, concepts, sources, etc.). The LLM updates it on every ingest. When answering a query, the LLM reads the index first to find relevant pages, then drills into them. This works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure.
|
||||
|
||||
**log.md** is chronological. It's an append-only record of what happened and when — ingests, queries, lint passes. A useful tip: if each entry starts with a consistent prefix (e.g. `## [2026-04-02] ingest | Article Title`), the log becomes parseable with simple unix tools — `grep "^## \[" log.md | tail -5` gives you the last 5 entries. The log gives you a timeline of the wiki's evolution and helps the LLM understand what's been done recently.
|
||||
|
||||
## Optional: CLI tools
|
||||
|
||||
At some point you may want to build small tools that help the LLM operate on the wiki more efficiently. A search engine over the wiki pages is the most obvious one — at small scale the index file is enough, but as the wiki grows you want proper search. [qmd](https://github.com/tobi/qmd) is a good option: it's a local search engine for markdown files with hybrid BM25/vector search and LLM re-ranking, all on-device. It has both a CLI (so the LLM can shell out to it) and an MCP server (so the LLM can use it as a native tool). You could also build something simpler yourself — the LLM can help you vibe-code a naive search script as the need arises.
|
||||
|
||||
## Tips and tricks
|
||||
|
||||
- **Obsidian Web Clipper** is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection.
|
||||
- **Download images locally.** In Obsidian Settings → Files and links, set "Attachment folder path" to a fixed directory (e.g. `raw/assets/`). Then in Settings → Hotkeys, search for "Download" to find "Download attachments for current file" and bind it to a hotkey (e.g. Ctrl+Shift+D). After clipping an article, hit the hotkey and all images get downloaded to local disk. This is optional but useful — it lets the LLM view and reference images directly instead of relying on URLs that may break. Note that LLMs can't natively read markdown with inline images in one pass — the workaround is to have the LLM read the text first, then view some or all of the referenced images separately to gain additional context. It's a bit clunky but works well enough.
|
||||
- **Obsidian's graph view** is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans.
|
||||
- **Marp** is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content.
|
||||
- **Dataview** is an Obsidian plugin that runs queries over page frontmatter. If your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables and lists.
|
||||
- The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free.
|
||||
|
||||
## Why this works
|
||||
|
||||
The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.
|
||||
|
||||
The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else.
|
||||
|
||||
The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. Bush's vision was closer to this than to what the web became: private, actively curated, with the connections between documents as valuable as the documents themselves. The part he couldn't solve was who does the maintenance. The LLM handles that.
|
||||
|
||||
|
||||
## Note
|
||||
|
||||
This document is intentionally abstract. It describes the idea, not a specific implementation. The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice. Everything mentioned above is optional and modular — pick what's useful, ignore what isn't. For example: your sources might be text-only, so you don't need image handling at all. Your wiki might be small enough that the index file is all you need, no search engine required. You might not care about slide decks and just want markdown pages. You might want a completely different set of output formats. The right way to use this is to share it with your LLM agent and work together to instantiate a version that fits your needs. The document's only job is to communicate the pattern. Your LLM can figure out the rest.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Raw Source
|
||||
|
||||
LLM Wiki code must live in the standalone plugin package.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Knowledge
|
||||
|
||||
The wiki stores durable knowledge as local markdown files.
|
||||
+3
@@ -0,0 +1,3 @@
|
||||
# Plugin Boundaries
|
||||
|
||||
LLM Wiki routes, prompts, UI, tools, and migrations belong inside the plugin.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Index
|
||||
|
||||
Catalog of durable wiki pages and linked project standups. Updated on every ingest or Paperclip distill.
|
||||
|
||||
## Sources
|
||||
|
||||
_(none yet)_
|
||||
|
||||
## Projects
|
||||
|
||||
_(none yet)_
|
||||
|
||||
## Entities
|
||||
|
||||
_(none yet)_
|
||||
|
||||
## Concepts
|
||||
|
||||
_(none yet)_
|
||||
|
||||
## Synthesis
|
||||
|
||||
_(none yet)_
|
||||
@@ -0,0 +1,10 @@
|
||||
# Log
|
||||
|
||||
Append-only chronological record of wiki operations.
|
||||
|
||||
## [2026-05-03] setup | wiki initialized
|
||||
- created `AGENTS.md` (schema)
|
||||
- created `raw/` for source documents
|
||||
- created `wiki/` skeleton: `index.md`, `log.md`, `sources/`, `projects/`, `entities/`, `concepts/`, `synthesis/`
|
||||
- created `wiki/projects/` for Paperclip project overviews and standups
|
||||
- pattern reference: `IDEA.md` (Karpathy "LLM Wiki" gist, https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
|
||||
@@ -0,0 +1 @@
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_instances (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
root_folder_key text NOT NULL DEFAULT 'wiki-root',
|
||||
configured_root_path text,
|
||||
schema_version integer NOT NULL DEFAULT 1,
|
||||
settings jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
managed_agent_key text,
|
||||
managed_project_key text,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
UNIQUE (company_id, wiki_id)
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_sources (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
source_type text NOT NULL,
|
||||
title text,
|
||||
url text,
|
||||
raw_path text NOT NULL,
|
||||
content_hash text NOT NULL,
|
||||
status text NOT NULL DEFAULT 'captured',
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_pages (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
path text NOT NULL,
|
||||
title text,
|
||||
page_type text,
|
||||
frontmatter jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
source_refs jsonb NOT NULL DEFAULT '[]'::jsonb,
|
||||
backlinks jsonb NOT NULL DEFAULT '[]'::jsonb,
|
||||
content_hash text,
|
||||
current_revision_id uuid,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
UNIQUE (company_id, wiki_id, path)
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
page_id uuid REFERENCES plugin_llm_wiki_8f50da974f.wiki_pages(id) ON DELETE CASCADE,
|
||||
operation_id uuid,
|
||||
path text NOT NULL,
|
||||
content_hash text NOT NULL,
|
||||
summary text,
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_operations (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
operation_type text NOT NULL,
|
||||
status text NOT NULL,
|
||||
hidden_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
|
||||
project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL,
|
||||
run_ids jsonb NOT NULL DEFAULT '[]'::jsonb,
|
||||
cost_cents integer NOT NULL DEFAULT 0,
|
||||
warnings jsonb NOT NULL DEFAULT '[]'::jsonb,
|
||||
affected_pages jsonb NOT NULL DEFAULT '[]'::jsonb,
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
hidden_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
|
||||
agent_session_id text,
|
||||
status text NOT NULL DEFAULT 'active',
|
||||
filed_outputs jsonb NOT NULL DEFAULT '[]'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_resource_bindings (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
resource_kind text NOT NULL,
|
||||
resource_key text NOT NULL,
|
||||
resolved_id uuid,
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
UNIQUE (company_id, wiki_id, resource_kind, resource_key)
|
||||
);
|
||||
@@ -0,0 +1,88 @@
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
source_scope text NOT NULL,
|
||||
scope_key text NOT NULL,
|
||||
project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE,
|
||||
root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE,
|
||||
source_kind text NOT NULL DEFAULT 'paperclip_issue_history',
|
||||
last_processed_at timestamptz,
|
||||
last_observed_at timestamptz,
|
||||
pending_event_count integer NOT NULL DEFAULT 0,
|
||||
last_successful_run_id uuid,
|
||||
last_source_hash text,
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
UNIQUE (company_id, wiki_id, source_scope, scope_key, source_kind)
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
work_item_kind text NOT NULL,
|
||||
status text NOT NULL DEFAULT 'pending',
|
||||
priority text NOT NULL DEFAULT 'medium',
|
||||
project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE,
|
||||
root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE,
|
||||
requested_by_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
|
||||
idempotency_key text,
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
UNIQUE (company_id, wiki_id, idempotency_key)
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
cursor_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors(id) ON DELETE SET NULL,
|
||||
work_item_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items(id) ON DELETE SET NULL,
|
||||
project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL,
|
||||
root_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
|
||||
source_window_start timestamptz,
|
||||
source_window_end timestamptz,
|
||||
source_hash text,
|
||||
status text NOT NULL,
|
||||
operation_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
|
||||
retry_count integer NOT NULL DEFAULT 0,
|
||||
cost_cents integer NOT NULL DEFAULT 0,
|
||||
warnings jsonb NOT NULL DEFAULT '[]'::jsonb,
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
distillation_run_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_runs(id) ON DELETE CASCADE,
|
||||
project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL,
|
||||
root_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
|
||||
source_hash text NOT NULL,
|
||||
max_characters integer NOT NULL,
|
||||
clipped boolean NOT NULL DEFAULT false,
|
||||
source_refs jsonb NOT NULL DEFAULT '[]'::jsonb,
|
||||
bundle_markdown text NOT NULL,
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL,
|
||||
project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE,
|
||||
root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE,
|
||||
page_path text NOT NULL,
|
||||
last_applied_source_hash text,
|
||||
last_distillation_run_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_runs(id) ON DELETE SET NULL,
|
||||
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
UNIQUE (company_id, wiki_id, page_path)
|
||||
);
|
||||
@@ -0,0 +1,236 @@
|
||||
CREATE TABLE IF NOT EXISTS plugin_llm_wiki_8f50da974f.wiki_spaces (
|
||||
id uuid PRIMARY KEY,
|
||||
company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
|
||||
wiki_id text NOT NULL DEFAULT 'default',
|
||||
slug text NOT NULL,
|
||||
display_name text NOT NULL,
|
||||
space_type text NOT NULL DEFAULT 'local_folder',
|
||||
folder_mode text NOT NULL DEFAULT 'managed_subfolder',
|
||||
root_folder_key text NOT NULL DEFAULT 'wiki-root',
|
||||
path_prefix text,
|
||||
configured_root_path text,
|
||||
access_scope text NOT NULL DEFAULT 'shared',
|
||||
owner_user_id text,
|
||||
owner_agent_id uuid REFERENCES public.agents(id) ON DELETE SET NULL,
|
||||
team_key text,
|
||||
settings jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
status text NOT NULL DEFAULT 'active',
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
UNIQUE (company_id, wiki_id, slug)
|
||||
);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS wiki_spaces_company_status_idx
|
||||
ON plugin_llm_wiki_8f50da974f.wiki_spaces (company_id, wiki_id, status);
|
||||
|
||||
WITH wiki_pairs AS (
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_instances
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_sources
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_pages
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_page_revisions
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_operations
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_query_sessions
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_distillation_runs
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_source_snapshots
|
||||
UNION
|
||||
SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_page_bindings
|
||||
)
|
||||
INSERT INTO plugin_llm_wiki_8f50da974f.wiki_spaces
|
||||
(id, company_id, wiki_id, slug, display_name, space_type, folder_mode, root_folder_key, path_prefix, access_scope, status)
|
||||
SELECT (
|
||||
substr(md5(company_id::text || ':' || wiki_id || ':default'), 1, 8) || '-' ||
|
||||
substr(md5(company_id::text || ':' || wiki_id || ':default'), 9, 4) || '-' ||
|
||||
'4' || substr(md5(company_id::text || ':' || wiki_id || ':default'), 14, 3) || '-' ||
|
||||
'8' || substr(md5(company_id::text || ':' || wiki_id || ':default'), 18, 3) || '-' ||
|
||||
substr(md5(company_id::text || ':' || wiki_id || ':default'), 21, 12)
|
||||
)::uuid,
|
||||
company_id,
|
||||
wiki_id,
|
||||
'default',
|
||||
'default',
|
||||
'local_folder',
|
||||
'managed_subfolder',
|
||||
'wiki-root',
|
||||
NULL,
|
||||
'shared',
|
||||
'active'
|
||||
FROM wiki_pairs
|
||||
ON CONFLICT (company_id, wiki_id, slug) DO NOTHING;
|
||||
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_sources ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_operations ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings ADD COLUMN IF NOT EXISTS space_id uuid;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.wiki_sources t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.wiki_pages t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.wiki_page_revisions t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.wiki_operations t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.wiki_query_sessions t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
UPDATE plugin_llm_wiki_8f50da974f.paperclip_page_bindings t
|
||||
SET space_id = s.id
|
||||
FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
|
||||
WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
|
||||
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_sources ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_operations ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots ALTER COLUMN space_id SET NOT NULL;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings ALTER COLUMN space_id SET NOT NULL;
|
||||
|
||||
DO $$
|
||||
DECLARE
|
||||
target record;
|
||||
constraint_name text;
|
||||
BEGIN
|
||||
FOR target IN
|
||||
SELECT * FROM (VALUES
|
||||
('wiki_pages', ARRAY['company_id', 'wiki_id', 'path']::text[]),
|
||||
('paperclip_distillation_cursors', ARRAY['company_id', 'wiki_id', 'source_scope', 'scope_key', 'source_kind']::text[]),
|
||||
('paperclip_distillation_work_items', ARRAY['company_id', 'wiki_id', 'idempotency_key']::text[]),
|
||||
('paperclip_page_bindings', ARRAY['company_id', 'wiki_id', 'page_path']::text[])
|
||||
) AS targets(table_name, column_names)
|
||||
LOOP
|
||||
FOR constraint_name IN
|
||||
SELECT c.conname
|
||||
FROM pg_constraint c
|
||||
JOIN pg_class t ON t.oid = c.conrelid
|
||||
JOIN pg_namespace n ON n.oid = t.relnamespace
|
||||
WHERE n.nspname = 'plugin_llm_wiki_8f50da974f'
|
||||
AND t.relname = target.table_name
|
||||
AND c.contype = 'u'
|
||||
AND (
|
||||
SELECT array_agg(a.attname ORDER BY constraint_columns.ordinality)::text[]
|
||||
FROM unnest(c.conkey) WITH ORDINALITY AS constraint_columns(attnum, ordinality)
|
||||
JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = constraint_columns.attnum
|
||||
) = target.column_names
|
||||
LOOP
|
||||
EXECUTE format('ALTER TABLE %I.%I DROP CONSTRAINT %I', 'plugin_llm_wiki_8f50da974f', target.table_name, constraint_name);
|
||||
END LOOP;
|
||||
END LOOP;
|
||||
END $$;
|
||||
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
|
||||
DROP CONSTRAINT IF EXISTS wiki_pages_company_wiki_space_path_key;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
|
||||
ADD CONSTRAINT wiki_pages_company_wiki_space_path_key UNIQUE (company_id, wiki_id, space_id, path);
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
|
||||
DROP CONSTRAINT IF EXISTS distillation_cursors_company_wiki_space_scope_key;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
|
||||
ADD CONSTRAINT distillation_cursors_company_wiki_space_scope_key UNIQUE (company_id, wiki_id, space_id, source_scope, scope_key, source_kind);
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
|
||||
DROP CONSTRAINT IF EXISTS distillation_work_items_company_wiki_space_idempotency_key;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
|
||||
ADD CONSTRAINT distillation_work_items_company_wiki_space_idempotency_key UNIQUE (company_id, wiki_id, space_id, idempotency_key);
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
|
||||
DROP CONSTRAINT IF EXISTS page_bindings_company_wiki_space_page_path_key;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
|
||||
ADD CONSTRAINT page_bindings_company_wiki_space_page_path_key UNIQUE (company_id, wiki_id, space_id, page_path);
|
||||
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_sources
|
||||
DROP CONSTRAINT IF EXISTS wiki_sources_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_sources
|
||||
ADD CONSTRAINT wiki_sources_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
|
||||
DROP CONSTRAINT IF EXISTS wiki_pages_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
|
||||
ADD CONSTRAINT wiki_pages_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions
|
||||
DROP CONSTRAINT IF EXISTS wiki_page_revisions_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions
|
||||
ADD CONSTRAINT wiki_page_revisions_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_operations
|
||||
DROP CONSTRAINT IF EXISTS wiki_operations_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_operations
|
||||
ADD CONSTRAINT wiki_operations_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions
|
||||
DROP CONSTRAINT IF EXISTS wiki_query_sessions_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions
|
||||
ADD CONSTRAINT wiki_query_sessions_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
|
||||
DROP CONSTRAINT IF EXISTS paperclip_distillation_cursors_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
|
||||
ADD CONSTRAINT paperclip_distillation_cursors_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
|
||||
DROP CONSTRAINT IF EXISTS paperclip_distillation_work_items_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
|
||||
ADD CONSTRAINT paperclip_distillation_work_items_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs
|
||||
DROP CONSTRAINT IF EXISTS paperclip_distillation_runs_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs
|
||||
ADD CONSTRAINT paperclip_distillation_runs_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots
|
||||
DROP CONSTRAINT IF EXISTS paperclip_source_snapshots_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots
|
||||
ADD CONSTRAINT paperclip_source_snapshots_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
|
||||
DROP CONSTRAINT IF EXISTS paperclip_page_bindings_space_id_fk;
|
||||
ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
|
||||
ADD CONSTRAINT paperclip_page_bindings_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
|
||||
|
||||
CREATE INDEX IF NOT EXISTS wiki_sources_space_idx ON plugin_llm_wiki_8f50da974f.wiki_sources (company_id, wiki_id, space_id, created_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS wiki_operations_space_idx ON plugin_llm_wiki_8f50da974f.wiki_operations (company_id, wiki_id, space_id, created_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS wiki_query_sessions_space_idx ON plugin_llm_wiki_8f50da974f.wiki_query_sessions (company_id, wiki_id, space_id, updated_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS distillation_runs_space_idx ON plugin_llm_wiki_8f50da974f.paperclip_distillation_runs (company_id, wiki_id, space_id, created_at DESC);
|
||||
@@ -0,0 +1,47 @@
|
||||
{
|
||||
"name": "@paperclipai/plugin-llm-wiki",
|
||||
"version": "0.1.0",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"description": "Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.",
|
||||
"scripts": {
|
||||
"prebuild": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps",
|
||||
"build": "node ./esbuild.config.mjs",
|
||||
"build:rollup": "rollup -c",
|
||||
"dev": "node ./esbuild.config.mjs --watch",
|
||||
"dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
|
||||
"test": "vitest run --config ./vitest.config.ts",
|
||||
"typecheck": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && tsc --noEmit"
|
||||
},
|
||||
"paperclipPlugin": {
|
||||
"manifest": "./dist/manifest.js",
|
||||
"worker": "./dist/worker.js",
|
||||
"ui": "./dist/ui/"
|
||||
},
|
||||
"keywords": [
|
||||
"paperclip",
|
||||
"plugin",
|
||||
"automation",
|
||||
"wiki",
|
||||
"knowledge"
|
||||
],
|
||||
"author": "Paperclip",
|
||||
"license": "MIT",
|
||||
"devDependencies": {
|
||||
"@paperclipai/plugin-sdk": "workspace:*",
|
||||
"@rollup/plugin-node-resolve": "^16.0.1",
|
||||
"@rollup/plugin-typescript": "^12.1.2",
|
||||
"@types/node": "^24.6.0",
|
||||
"@types/react": "^19.0.8",
|
||||
"@types/react-dom": "^19.0.3",
|
||||
"esbuild": "^0.27.3",
|
||||
"react-dom": "^19.0.0",
|
||||
"rollup": "^4.38.0",
|
||||
"tslib": "^2.8.1",
|
||||
"typescript": "^5.7.3",
|
||||
"vitest": "^3.0.5"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"react": ">=18"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,28 @@
|
||||
import { nodeResolve } from "@rollup/plugin-node-resolve";
|
||||
import typescript from "@rollup/plugin-typescript";
|
||||
import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
|
||||
|
||||
const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
|
||||
|
||||
function withPlugins(config) {
|
||||
if (!config) return null;
|
||||
return {
|
||||
...config,
|
||||
plugins: [
|
||||
nodeResolve({
|
||||
extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs"],
|
||||
}),
|
||||
typescript({
|
||||
tsconfig: "./tsconfig.json",
|
||||
declaration: false,
|
||||
declarationMap: false,
|
||||
}),
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
export default [
|
||||
withPlugins(presets.rollup.manifest),
|
||||
withPlugins(presets.rollup.worker),
|
||||
withPlugins(presets.rollup.ui),
|
||||
].filter(Boolean);
|
||||
@@ -0,0 +1,34 @@
|
||||
# LLM Wiki Maintainer Skills
|
||||
|
||||
This folder is the plugin-level source for LLM Wiki managed company skills. Paperclip installs these skills into the company skill library and syncs them onto the Wiki Maintainer agent. The Wiki Maintainer's identity and operating loop live in `agents/wiki-maintainer/AGENTS.md`; the wiki-root `AGENTS.md` remains the wiki schema for page layout, citation style, and log format.
|
||||
|
||||
Each skill is an isolated SKILL.md describing one job — when to invoke it, the inputs that must be true before starting, the steps, and the durable output the operation must leave behind.
|
||||
|
||||
## Skill registry
|
||||
|
||||
| Skill | When to invoke |
|
||||
|---|---|
|
||||
| [`wiki-maintainer`](./wiki-maintainer/SKILL.md) | General LLM Wiki maintenance and tool-use guidance shared by the operation skills. |
|
||||
| [`wiki-ingest`](./wiki-ingest/SKILL.md) | A new file landed in `raw/` and the operation issue says "ingest" — turn the source into durable wiki pages. |
|
||||
| [`wiki-query`](./wiki-query/SKILL.md) | The user asked the wiki a question; answer with citations and offer to file durable synthesis back into `wiki/`. |
|
||||
| [`wiki-lint`](./wiki-lint/SKILL.md) | A lint or health-check operation — audit for contradictions, orphan pages, weak provenance, broken links, missing concept pages. |
|
||||
| [`paperclip-distill`](./paperclip-distill/SKILL.md) | Cursor-window, distill, or backfill operation on Paperclip activity — write a wiki-insightful project page, decisions log, and history note. |
|
||||
| [`index-refresh`](./index-refresh/SKILL.md) | Refresh `wiki/index.md` so each entry has a tight, scannable summary; flag drift between the index and recent log activity. |
|
||||
|
||||
## Layering
|
||||
|
||||
```
|
||||
AGENTS.md (wiki root) ← schema for the wiki itself: page conventions, frontmatter, voice
|
||||
agents/wiki-maintainer/AGENTS.md ← agent identity and operating loop
|
||||
skills/<skill>/SKILL.md ← plugin-managed company skills installed onto the maintainer
|
||||
```
|
||||
|
||||
When a skill conflicts with the wiki-root `AGENTS.md`, the wiki schema wins for page format/voice and the skill wins for operation flow. When a skill conflicts with the agent's `AGENTS.md`, the agent file wins for identity and the skill wins for the operation procedure.
|
||||
|
||||
## Skill conventions
|
||||
|
||||
- Front matter has `name` (kebab-case) and `description` (one or two sentences with the trigger condition).
|
||||
- Each skill names the input it expects (e.g. an operation issue with `originKind` ending in `:ingest`, a captured `raw/` path, a Paperclip source bundle).
|
||||
- Each skill ends with a verification checklist — what must be true before the operation issue is closed `done`.
|
||||
- Skills cite the wiki-plugin tools they rely on (`wiki_search`, `wiki_read_page`, `wiki_write_page`, `wiki_read_source`, `wiki_list_sources`).
|
||||
- Skills do not duplicate the page conventions from the wiki root `AGENTS.md`. They reference it instead.
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
name: index-refresh
|
||||
description: Use when an operation issue is an index refresh — typically the hourly index-refresh routine. Rebuild `wiki/index.md` so each entry has a tight, scannable one-line summary and the catalog tracks the actual contents of `wiki/`. Resolve drift between the index and recent log activity, but do not edit page content.
|
||||
---
|
||||
|
||||
# Index Refresh
|
||||
|
||||
Keep `wiki/index.md` accurate and scannable. The index is the maintainer's first stop for navigation — its quality determines how cheap every subsequent operation becomes.
|
||||
|
||||
## Inputs
|
||||
|
||||
- An operation issue with `operationType: "index"` (or the `index-refresh` routine title).
|
||||
- The operation issue's target `wikiId`, `spaceSlug`, and space root. Refresh only that space unless the issue explicitly says this is a multi-space sweep.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Read the target space's `wiki/index.md`** as it currently stands.
|
||||
2. **Walk the target space's `wiki/`.** `wiki/projects/<slug>/standup.md` entries are current-state companions for durable `wiki/projects/<slug>/index.md` pages; index them only as links attached to the matching project entry. Walk `wiki/` by category (`sources/`, `projects/`, `entities/`, `concepts/`, `synthesis/`, plus any custom subdirectories the wiki schema added).
|
||||
3. **Read the target space's last ~50 entries of `wiki/log.md`** to spot pages that were created or substantially changed but never made it to the index.
|
||||
4. **Per category, produce sorted entries** of the form:
|
||||
```
|
||||
- [[<path>]] — <one-line summary>
|
||||
```
|
||||
The summary is one factual sentence pulled from the page's first paragraph or its title. **No status, no datestamps in the index** — those belong in the page itself or in the log.
|
||||
5. **Drop entries whose page no longer exists.** Note the deletion in the log:
|
||||
```
|
||||
## [YYYY-MM-DD] index-refresh | reconciled
|
||||
- removed: [[wiki/old-page]] (page deleted)
|
||||
- added: [[wiki/new-page]] — <summary>
|
||||
```
|
||||
6. **Add entries for pages that exist on disk but were missing from the index.** Skip `wiki/log.md` and `wiki/index.md` themselves. For standalone `wiki/projects/<slug>/standup.md` without a matching durable project page, add it under Projects and flag it for later durable-page distillation.
|
||||
7. **Write project entries editorially.** The Projects section should group work by the project's concept and purpose, not by issue ids, dates, statuses, UUIDs, or source metadata. Link task identifiers only as supporting evidence.
|
||||
8. **Preserve custom categories.** If the wiki has added e.g. `wiki/papers/` or `wiki/runbooks/`, keep its index section. Do not collapse to the default five categories.
|
||||
9. **Append a log entry** with counts:
|
||||
```
|
||||
## [YYYY-MM-DD] index-refresh | added=N removed=M
|
||||
- operation issue: <issue identifier>
|
||||
```
|
||||
If the index was already accurate, the log entry says `added=0 removed=0` — still write it so future audits can see the run happened.
|
||||
|
||||
## What this skill does NOT do
|
||||
|
||||
- Does not change page content.
|
||||
- Does not resolve contradictions, fix broken links, or fill concept gaps. Those go to the next `wiki-lint` run.
|
||||
- Does not write summaries that are not already supported by the page itself. If a page lacks a clear first paragraph to summarise, flag it for `wiki-lint`.
|
||||
|
||||
## Voice
|
||||
|
||||
- Index entries are one factual line per page, present tense.
|
||||
- No emojis, no statuses, no dates in `wiki/index.md`. Dates live in the log.
|
||||
|
||||
## Verification
|
||||
|
||||
Before closing the operation issue:
|
||||
|
||||
- [ ] `wiki/index.md` matches the actual contents of `wiki/` — no missing pages, no dangling entries.
|
||||
- [ ] Project entries include current `wiki/projects/<slug>/standup.md` links when standups exist.
|
||||
- [ ] Each index line has the form `- [[path]] — <summary>`.
|
||||
- [ ] Custom category sections are preserved.
|
||||
- [ ] `wiki/log.md` has the index-refresh entry with counts (even if the counts are zero).
|
||||
- [ ] No page bodies were modified. No file under `raw/` was modified.
|
||||
|
||||
## Tools
|
||||
|
||||
`wiki_search`, `wiki_read_page`, `wiki_write_page` (for `wiki/index.md` and `wiki/log.md` only). Always include the operation issue's `wikiId` and `spaceSlug`.
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
name: paperclip-distill
|
||||
description: Use when an operation issue is a Paperclip cursor-window, distill, or backfill — `operationType: "distill"` or `"backfill"` and the body references a Paperclip source bundle for a project or root issue. Turn raw Paperclip activity into a wiki-insightful project page, decisions log, and history note. This skill exists specifically to replace the stiff, datestamp-heavy templated output that the deterministic distiller produces.
|
||||
---
|
||||
|
||||
# Paperclip Distill
|
||||
|
||||
Distill Paperclip project, issue, comment, and document activity into durable wiki pages. The success criterion is **wiki-insightful, not procedural**: a reader who has never seen Paperclip should learn what the project is, what was decided, what is at risk, and what the current state is — without scanning a list of `## [YYYY-MM-DD]` headers.
|
||||
|
||||
## When this skill is needed
|
||||
|
||||
- Cursor-window distillation: the routine fed you a bounded source bundle of recent Paperclip activity for one project or root issue.
|
||||
- Backfill: the user asked to seed the wiki with the historical activity of a project or root issue. Source window may be wide.
|
||||
- Manual `distill-paperclip-now` request from the UI.
|
||||
|
||||
If the operation issue is `operationType: "ingest"` (raw file) or `operationType: "query"`, this is the wrong skill — use `wiki-ingest` or `wiki-query`.
|
||||
|
||||
## Destination space
|
||||
|
||||
In Phase 1, every Paperclip distill, backfill, and cursor-window operation writes into the
|
||||
default wiki space. The operation issue should always carry `spaceSlug: "default"`. If an
|
||||
operation issue passes any other slug, stop and surface the mismatch in a comment — do not
|
||||
write Paperclip-derived pages into a non-default space.
|
||||
|
||||
This rule is destination-only. The Paperclip source scope (which projects, root issues,
|
||||
comments, documents are read) is set elsewhere in the operation issue and is independent of
|
||||
the destination.
|
||||
|
||||
## Inputs
|
||||
|
||||
- A Paperclip source bundle (issue list, comment refs, document refs, source hash, cursor window).
|
||||
- An existing or planned `wiki/projects/<slug>/standup.md` page path.
|
||||
- An existing or planned `wiki/projects/<slug>/index.md` page path.
|
||||
- The operation issue's target `wikiId`, `spaceSlug`, space root, and the target space's `AGENTS.md` for page conventions.
|
||||
- The current `wiki/projects/<slug>/standup.md`, `wiki/projects/<slug>/index.md`, `decisions.md`, and `history.md` if they already exist (so you write a *patch*, not a rewrite).
|
||||
|
||||
## Paperclip Asset Gate
|
||||
|
||||
Do not treat Paperclip assets/attachments or issue work products as source text for this skill.
|
||||
|
||||
- Allowed Paperclip body text: issue descriptions, comment bodies, document bodies.
|
||||
- Assets/attachments are metadata-only until a separate approved extraction policy exists.
|
||||
- Work products are metadata-only until a separate approved extraction policy exists.
|
||||
- Never fetch `/api/assets/:id/content`.
|
||||
- Never dereference a work-product `url`, preview URL, artifact URL, or other linked destination from this skill.
|
||||
- If an operator asks for attachment/work-product content distillation, stop and point them at the Phase 5 asset/work-product security gate policy instead of improvising.
|
||||
|
||||
## Anti-patterns to avoid
|
||||
|
||||
The deterministic templating this skill replaces produced these failure modes — do not reproduce them:
|
||||
|
||||
1. **Datestamp-as-section-header.** Lines like `## [2026-04-15] paperclip-distill | proposed` belong in `wiki/log.md`, not in the project page. The project page is durable knowledge; the log is the audit trail.
|
||||
2. **Procedural status lists.** `Issue mix: 3 todo, 5 in_progress, 2 done` tells the reader nothing they could not read off Paperclip directly. State *what is happening and why it matters*, then cite the issues that constitute the evidence.
|
||||
3. **One-line-per-issue dumps.** A page that is mostly `- PAP-1234: title (in_progress, updated 2026-...)` is an issue list, not a wiki page. Group issues by what they are *about* (a decision, a risk, a workstream) and cite multiple issues per bullet when they share a story.
|
||||
4. **Mechanical "Current as of" timestamps everywhere.** One `current_as_of` in frontmatter is enough.
|
||||
5. **No interpretation.** "Active issues: PAP-A, PAP-B, PAP-C" is bookkeeping. "The team is concentrating on the schema migration ([PAP-A], [PAP-B]) and has parked the index work pending capacity ([PAP-C])." is wiki-insightful.
|
||||
6. **Opaque identifiers in prose.** UUIDs, cursor ids, source hashes, run ids, and raw metadata belong in logs or frontmatter when needed, not in executive-facing project narrative.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Read the bundle in full.** Don't sample. Read every issue title, every comment, every document key the bundle includes. Note: which issues are decisions, which are risks/blockers, which are recently completed, which are inflight.
|
||||
2. **Read the existing project page** (if any) so you write a patch, not a rewrite. The "Decisions" section in particular accumulates over time — never wipe accepted decisions; supersede them with `> ⚠ reversed by ...` callouts when something later overrides them.
|
||||
3. **Read the target space's `AGENTS.md`** for page conventions: filename style, YAML frontmatter shape, link style, voice. Always pass the operation issue's `wikiId` and `spaceSlug` to LLM Wiki tools.
|
||||
4. **Write `wiki/projects/<slug>/standup.md` first.** Every Paperclip project represented in the wiki must have this file. It is the executive standup: where the project stands today, what changed recently, what is blocked or risky, and what happens next. Use stable sections, in this order:
|
||||
- Frontmatter (`type: project-standup`, `project: <slug>`, `current_as_of: YYYY-MM-DD`, `sources`).
|
||||
- **Executive Readout** — one short paragraph that explains the current project posture in plain language.
|
||||
- **What Changed** — the meaningful work completed or advanced since the last window. Group by concept; cite issues/comments/documents only as evidence.
|
||||
- **Decisions** — accepted/rejected/reversed decisions that changed the project direction. Omit when none exist.
|
||||
- **Blockers / Risks** — current blockers and risks with named owner or next action when the source provides one.
|
||||
- **Next Actions** — concrete next actions and owners inferred from Paperclip issues, not vague aspirations.
|
||||
- **Links** — durable wiki project page and relevant Paperclip project/issues/documents.
|
||||
Rewrite the standup to today's state. Do not append endless dated sections; the audit trail belongs in `wiki/log.md` and Paperclip comments.
|
||||
5. **Write `wiki/projects/<slug>/index.md`** with these stable sections, in this order:
|
||||
- Frontmatter (`type: project`, `current_as_of: YYYY-MM-DD`, `tags`, `sources`).
|
||||
- **Overview** — 2–4 sentences saying what the project is and why it exists. Use the project description if it exists; otherwise synthesise it from the root issue.
|
||||
- **Current Direction** — narrative paragraph naming the active workstreams, the immediate next concrete deliverable, and the stance on risks. Cite 2–4 issues, do not list 20.
|
||||
- **Workstreams** — a short, grouped list. Each line is a workstream or idea, not an issue.
|
||||
- **Decisions** — accepted and reversed decisions with one paragraph each. Each decision cites the issue / approval / comment that ratified it. Format: `### Decision — short title` then a paragraph; never a bare bullet list.
|
||||
- **Open Risks / Blockers** — what could derail the project, with the issue ref that surfaces it. Skip this section when the bundle has no risk signal — do not pad with `_(none)_`.
|
||||
- **References** — readable links to the current standup and supporting Paperclip tasks/documents. Keep hashes and cursor ids out of the narrative.
|
||||
6. **Optionally write `wiki/projects/<slug>/decisions.md`** when the project has accumulated more decisions than the project page can carry without becoming a wall of text. Each decision is a `## ` section with: short title, accepted/reversed/superseded status, one-paragraph rationale, citing the source. *Do not* duplicate decisions already on the project page — link instead.
|
||||
7. **Optionally write `wiki/projects/<slug>/history.md`** for a compact narrative timeline of meaningful project changes. **Not** an issue dump — group by phase ("Discovery", "Architecture", "Build", "Stabilisation"), not by date. Each phase is a paragraph that cites the 2–4 issues that defined it.
|
||||
8. **Refresh `wiki/index.md`** under the `## Projects` section — one line per durable project page with a one-sentence summary of the project's purpose, plus a link to the current `wiki/projects/<slug>/standup.md` when present.
|
||||
9. **Append `wiki/log.md`** entry — this is where the datestamp belongs:
|
||||
```
|
||||
## [YYYY-MM-DD] paperclip-distill | <project name>
|
||||
- standup: wiki/projects/<slug>/standup.md
|
||||
- page: wiki/projects/<slug>/index.md
|
||||
- source hash: `<hash>`
|
||||
- cursor window: <start> → <end>
|
||||
- notes: <one line on what changed in this distill, e.g. "decisions section grew with PAP-X reversal", "low-signal window, no page changes">
|
||||
```
|
||||
10. **Surface bundle warnings** (clipped sources, low signal, stale hash). Bundle warnings → `human_review_required: true` on the patch. Do not paper over them.
|
||||
|
||||
## Voice
|
||||
|
||||
- Past-tense for completed work, present-tense for current state, future-tense only with citation ("the team plans to … per [[…]]").
|
||||
- Cite Paperclip source refs inline using their issue identifier (e.g. `PAP-3179`), not opaque UUIDs.
|
||||
- Use issue links as evidence, not as the shape of the page. Headings and paragraphs should be organized by concepts, workstreams, decisions, and blockers.
|
||||
- Wiki voice: terse, factual, neutral. No "the team is excited to" or "this initiative aims to".
|
||||
- Headings are about *content*, not metadata. `## Schema migration` not `## Active Issues`.
|
||||
|
||||
## When the bundle has no signal
|
||||
|
||||
If the bundle has no durable signal — no decisions, no risk, no completed work, only routine status churn — do **not** write a project page. Instead:
|
||||
|
||||
- Append a `paperclip-distill | low-signal skip` log entry naming the cursor window.
|
||||
- Close the operation issue with a one-line "no durable change in this window" comment.
|
||||
- Do not bump the source hash on a binding that has no proposed page.
|
||||
|
||||
## Verification
|
||||
|
||||
Before closing the operation issue:
|
||||
|
||||
- [ ] The project page reads as wiki content, not as a Paperclip status report. A reader new to the company should understand what the project is.
|
||||
- [ ] `wiki/projects/<slug>/standup.md` exists for the represented project and reads as an executive current-state update, not a raw issue dump.
|
||||
- [ ] Decisions section names decisions, not issues — every decision has a one-paragraph rationale and a citation.
|
||||
- [ ] The page contains exactly one `current_as_of` (in frontmatter), zero `## [YYYY-MM-DD]` headings (those go to the log).
|
||||
- [ ] Bundle warnings (clipped, low signal, stale hash) are surfaced; the patch carries `human_review_required: true` when the deployment is authenticated/public.
|
||||
- [ ] `wiki/index.md` and `wiki/log.md` are updated.
|
||||
- [ ] No file under `raw/` was modified.
|
||||
|
||||
## Tools
|
||||
|
||||
`wiki_search`, `wiki_read_page`, `wiki_write_page`, `wiki_list_sources`, `wiki_read_source`. Always include the operation issue's `wikiId` and `spaceSlug`. The Paperclip source bundle arrives as part of the operation context — you do not need to assemble it.
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: wiki-ingest
|
||||
description: Use when an operation issue asks you to ingest a captured source from `raw/` into the LLM Wiki, or when the user explicitly says "ingest <slug>". The issue body will name a file under `raw/` (e.g. `raw/karpathy-llm-wiki.md`) and ask for durable wiki pages. Do not invoke this skill for Paperclip activity bundles — those use `paperclip-distill` instead.
|
||||
---
|
||||
|
||||
# Wiki Ingest
|
||||
|
||||
Turn one source document into durable, interlinked wiki knowledge.
|
||||
|
||||
## Inputs
|
||||
|
||||
- An operation issue with `operationType: "ingest"` assigned to you.
|
||||
- A `raw/` path mentioned in the issue body (always treat `raw/` as immutable).
|
||||
- The operation issue's target `wikiId`, `spaceSlug`, and space root (otherwise stop and surface the missing config to the requester).
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Read context first.**
|
||||
- Read the target space's `AGENTS.md` for page conventions (filenames, frontmatter, voice, citation style).
|
||||
- Read the target space's `wiki/index.md` to see what already exists.
|
||||
- Read the target space's last ~20 entries of `wiki/log.md` to avoid re-ingesting a source or re-resolving a contradiction someone else already filed.
|
||||
2. **Read the source end to end** with `wiki_read_source`, passing the operation issue's `wikiId` and `spaceSlug`. Do not skim. Note the source's structure, claims, dates, and anything that contradicts existing pages.
|
||||
3. **Plan, then confirm — but only if the user is in the loop.** If the operation came from a routine (no live user), proceed. If a user is asking interactively, summarise the 3–5 takeaways you intend to file and ask which to emphasise before writing.
|
||||
4. **Write the source page** at `wiki/sources/<slug>.md` — ~300–800 words, frontmatter per the wiki schema, neutral voice, key claims with quoted excerpts where they carry weight. The source page is the canonical citation target for everything else this skill writes.
|
||||
5. **Update or create downstream pages** in `entities/`, `concepts/`, and `synthesis/`. A typical ingest touches 5–15 pages; resist creating pages for ideas that only appear once.
|
||||
6. **Wire the cross-links.** Every claim that comes from the source cites it as `(see [[wiki/sources/<slug>]])`. Every entity / concept mentioned by name on more than one page links to its dedicated page.
|
||||
7. **Flag contradictions; do not silently overwrite.** When new material disagrees with an existing page, append a `> ⚠ contradicted by [[wiki/sources/<slug>]] (YYYY-MM-DD)` callout to the older page and note the conflict in the log.
|
||||
8. **Refresh `wiki/index.md`** with one-line summaries for any new pages.
|
||||
9. **Append a log entry** in `wiki/log.md`:
|
||||
```
|
||||
## [YYYY-MM-DD] ingest | <source title>
|
||||
- source: raw/<filename>
|
||||
- new pages: [[...]], [[...]]
|
||||
- updated pages: [[...]], [[...]]
|
||||
- notes: <one-line synthesis or open question>
|
||||
```
|
||||
|
||||
## Voice
|
||||
|
||||
- Terse, factual, neutral. Reference material, not narrative.
|
||||
- No "Today I learned" or "This is interesting because" framing.
|
||||
- Quote the source verbatim when paraphrasing would lose precision.
|
||||
|
||||
## Verification
|
||||
|
||||
Before closing the operation issue:
|
||||
|
||||
- [ ] Source page exists at `wiki/sources/<slug>.md` with valid frontmatter and a `sources:` field pointing to the raw path.
|
||||
- [ ] Every new or updated page links back to the source page or a downstream page that does.
|
||||
- [ ] `wiki/index.md` lists every new page under the right category with a one-line summary.
|
||||
- [ ] `wiki/log.md` has the ingest entry with the exact filename heading format (so `grep "^## \[" wiki/log.md` keeps working).
|
||||
- [ ] Any contradiction between the new source and an older page is annotated, not silently overwritten.
|
||||
- [ ] No file under `raw/` was modified.
|
||||
|
||||
## Tools
|
||||
|
||||
`wiki_list_sources`, `wiki_read_source`, `wiki_search`, `wiki_read_page`, `wiki_write_page`. Always include the operation issue's `wikiId` and `spaceSlug`.
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: wiki-lint
|
||||
description: Use when an operation issue is a lint or health-check (`operationType: "lint"`) — typically the nightly lint routine or a manual "Run lint" from the UI. Audit the wiki for contradictions, orphans, weak provenance, broken links, and missing concept pages, and return a triage list — do not auto-fix.
|
||||
---
|
||||
|
||||
# Wiki Lint
|
||||
|
||||
Audit, do not edit. Return findings the maintainer (human or agent) can triage.
|
||||
|
||||
## Inputs
|
||||
|
||||
- An operation issue with `operationType: "lint"`.
|
||||
- The operation issue's target `wikiId`, `spaceSlug`, and space root. Lint only that space unless the issue explicitly says this is a multi-space sweep.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Walk the target space's `wiki/index.md` and wiki tree** with `wiki_search` and `wiki_read_page`, always passing the operation issue's `wikiId` and `spaceSlug`. Build a mental map of: pages that exist, pages referenced from `index.md`, pages referenced from other pages, and raw sources.
|
||||
2. **Check for the seven recurring issues**, in this order:
|
||||
1. **Contradictions** — two pages making incompatible claims about the same entity, decision, or status. Flag both pages, name the conflicting claims, and quote evidence.
|
||||
2. **Stale claims** — a page asserts X, but a newer source under `raw/` has superseded it. Flag the older page; never overwrite.
|
||||
3. **Orphan pages** — a `wiki/` page is not linked from `index.md` and not referenced from any other wiki page. Either it should be linked, removed, or merged.
|
||||
4. **Concept gaps** — a term appears on three or more pages but has no dedicated `wiki/concepts/<slug>.md`. Recommend creating one.
|
||||
5. **Broken `[[wiki-links]]`** — a link target file does not exist.
|
||||
6. **Weak provenance** — a non-trivial claim is uncited or cites only the wiki itself in a circle. The original source ref should be findable.
|
||||
7. **Index / log drift** — pages exist that are not in `index.md`, or `index.md` lists pages that no longer exist. Recent operations in `wiki/log.md` that did not produce a corresponding page change.
|
||||
3. **Return a triage list**, grouped by severity:
|
||||
- **critical**: contradictions, broken links to active pages, fabricated citations.
|
||||
- **medium**: stale claims, weak provenance, large concept gaps.
|
||||
- **low**: orphans, log drift, small index gaps.
|
||||
Each item has: file path, evidence (a 1–2 line quote), suggested fix, and the operation that should follow up (`ingest`, `paperclip-distill`, `index-refresh`, manual review).
|
||||
4. **Do not write to `wiki/`.** Lint is read-only by design — the maintainer or the routine that follows decides which findings to act on.
|
||||
5. **Append a log entry** describing the run:
|
||||
```
|
||||
## [YYYY-MM-DD] lint | <N findings, M critical>
|
||||
- operation issue: <issue identifier>
|
||||
- critical: <count>
|
||||
- medium: <count>
|
||||
- low: <count>
|
||||
```
|
||||
|
||||
## Voice
|
||||
|
||||
- Lead with the count by severity.
|
||||
- Each finding is one bullet. Resist commentary.
|
||||
- When in doubt about severity, say so and surface it as medium with a "verify" note.
|
||||
|
||||
## Verification
|
||||
|
||||
Before closing the operation issue:
|
||||
|
||||
- [ ] Findings are grouped by severity with file paths, evidence, and suggested fix per item.
|
||||
- [ ] No files under `raw/` were modified. No files under `wiki/` were modified except `wiki/log.md`.
|
||||
- [ ] If the run found nothing, the issue is closed with "no findings" and the log entry still exists so future audits can see this run happened.
|
||||
|
||||
## Tools
|
||||
|
||||
`wiki_search`, `wiki_read_page`, `wiki_list_sources`, `wiki_read_source`, `wiki_write_page` (only `wiki/log.md`). Always include the operation issue's `wikiId` and `spaceSlug`.
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
name: "LLM Wiki Maintainer"
|
||||
description: "Use the LLM Wiki plugin tools to maintain a cited local company wiki."
|
||||
---
|
||||
|
||||
# LLM Wiki Maintainer
|
||||
|
||||
Use this skill when maintaining the company LLM Wiki, answering questions from it, ingesting durable source material, refreshing the index, or linting wiki structure.
|
||||
|
||||
Before changing wiki files, resolve the configured wiki root, read its AGENTS.md, inspect wiki/index.md and recent wiki/log.md entries, then use the LLM Wiki plugin tools for source reads, page writes, patch proposals, backlinks, and logging.
|
||||
|
||||
Keep raw sources immutable, cite wiki pages and raw paths, update wiki/index.md when page navigation changes, and append a concise wiki/log.md entry for durable updates. For Paperclip project work, keep `wiki/projects/<project-slug>/standup.md` current as the executive status view and use `wiki/projects/<project-slug>/index.md` for durable project knowledge. Write project material as concept-grouped executive synthesis, not issue-id lists or metadata dumps.
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
name: wiki-query
|
||||
description: Use when an operation issue asks you to answer a question from the LLM Wiki — `operationType: "query"` and a question in the issue body. Answer with citations to wiki pages and raw sources, and offer to file durable synthesis back into `wiki/synthesis/` so the work compounds instead of disappearing into a chat thread.
|
||||
---
|
||||
|
||||
# Wiki Query
|
||||
|
||||
Answer a question from what the wiki actually contains, with citations.
|
||||
|
||||
## Inputs
|
||||
|
||||
- An operation issue with `operationType: "query"` and the question in the body.
|
||||
- The operation issue's target `wikiId`, `spaceSlug`, and space root.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Open the target space's `wiki/index.md` first** — it is the navigation aid. Identify candidate pages.
|
||||
2. **Read the candidate pages** end to end with `wiki_read_page`, always passing the operation issue's `wikiId` and `spaceSlug`. Follow `[[wiki-links]]` to neighbouring pages when the question spans entities or concepts.
|
||||
3. **Inspect raw sources** when a wiki page's claim feels thin. The wiki points to `raw/` precisely so you can verify before answering. Use `wiki_read_source`.
|
||||
4. **Answer the question** in the operation issue thread. Structure:
|
||||
- Direct answer first, in 1–4 sentences.
|
||||
- Then the supporting facts as bullet points, each with an inline citation: `(see [[wiki/concepts/managed-resources]])` or `(see raw/<filename>)`.
|
||||
- If you needed to read a raw source the wiki did not summarise, name that as a gap.
|
||||
5. **Decide whether the answer is durable.** If the question forced you to do real synthesis (a comparison, a tradeoff, a definition of something that isn't already a page), offer to file it under `wiki/synthesis/<slug>.md`. Do not write the synthesis page silently — it is opt-in. If the user accepts, write the page, link it from `wiki/index.md`, and append a `query | filed synthesis` log entry.
|
||||
6. **When the wiki cannot answer**, say so plainly. Suggest a source the user should ingest, a Paperclip project that would help if distilled, or a web lookup. Never bluff.
|
||||
|
||||
## Voice
|
||||
|
||||
- Lead with the answer.
|
||||
- Cite as you go, not in a footnote block at the end.
|
||||
- Use the wiki's terse, factual voice. The query response is itself a candidate for filing into `wiki/synthesis/`.
|
||||
|
||||
## Verification
|
||||
|
||||
Before closing the operation issue:
|
||||
|
||||
- [ ] Every claim in the answer cites a wiki page or raw source.
|
||||
- [ ] If the wiki was insufficient, that is stated directly with a concrete next step (ingest source X, distill project Y, web search Z).
|
||||
- [ ] If you wrote a synthesis page, `wiki/index.md` lists it and `wiki/log.md` has a `query | filed synthesis` entry.
|
||||
- [ ] No file under `raw/` was modified.
|
||||
|
||||
## Tools
|
||||
|
||||
`wiki_search`, `wiki_read_page`, `wiki_list_sources`, `wiki_read_source`, `wiki_write_page` (only when filing synthesis). Always include the operation issue's `wikiId` and `spaceSlug`.
|
||||
@@ -0,0 +1,601 @@
|
||||
import { readFileSync } from "node:fs";
|
||||
import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
|
||||
import { DEFAULT_AGENT_INSTRUCTION_FILES, DEFAULT_AGENT_INSTRUCTIONS } from "./templates.js";
|
||||
|
||||
export const PLUGIN_ID = "paperclipai.plugin-llm-wiki";
|
||||
export const WIKI_ROOT_FOLDER_KEY = "wiki-root";
|
||||
export const WIKI_MAINTAINER_AGENT_KEY = "wiki-maintainer";
|
||||
export const WIKI_MAINTAINER_SKILL_KEY = "wiki-maintainer";
|
||||
export const WIKI_INGEST_SKILL_KEY = "wiki-ingest";
|
||||
export const WIKI_QUERY_SKILL_KEY = "wiki-query";
|
||||
export const WIKI_LINT_SKILL_KEY = "wiki-lint";
|
||||
export const PAPERCLIP_DISTILL_SKILL_KEY = "paperclip-distill";
|
||||
export const INDEX_REFRESH_SKILL_KEY = "index-refresh";
|
||||
export const WIKI_PROJECT_KEY = "llm-wiki";
|
||||
export const CURSOR_WINDOW_ROUTINE_KEY = "cursor-window-processing";
|
||||
export const NIGHTLY_LINT_ROUTINE_KEY = "nightly-wiki-lint";
|
||||
export const INDEX_REFRESH_ROUTINE_KEY = "index-refresh";
|
||||
export const DEFAULT_MAX_SOURCE_BYTES = 250000;
|
||||
export const DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS = 12000;
|
||||
export const DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS = 60000;
|
||||
export const DEFAULT_MAX_PAPERCLIP_ROUTINE_RUN_CHARS = 120000;
|
||||
export const DEFAULT_PAPERCLIP_COST_CENTS_PER_1K_CHARS = 1;
|
||||
export const WIKI_MAINTENANCE_ROUTINE_KEYS = [
|
||||
CURSOR_WINDOW_ROUTINE_KEY,
|
||||
NIGHTLY_LINT_ROUTINE_KEY,
|
||||
INDEX_REFRESH_ROUTINE_KEY,
|
||||
] as const;
|
||||
export const WIKI_MANAGED_SKILL_KEYS = [
|
||||
WIKI_MAINTAINER_SKILL_KEY,
|
||||
WIKI_INGEST_SKILL_KEY,
|
||||
WIKI_QUERY_SKILL_KEY,
|
||||
WIKI_LINT_SKILL_KEY,
|
||||
PAPERCLIP_DISTILL_SKILL_KEY,
|
||||
INDEX_REFRESH_SKILL_KEY,
|
||||
] as const;
|
||||
|
||||
function canonicalSkillKey(skillKey: string) {
|
||||
return `plugin/paperclipai-plugin-llm-wiki/${skillKey}`;
|
||||
}
|
||||
|
||||
function skillMarkdown(skillKey: (typeof WIKI_MANAGED_SKILL_KEYS)[number]) {
|
||||
return readFileSync(new URL(`../skills/${skillKey}/SKILL.md`, import.meta.url), "utf8");
|
||||
}
|
||||
|
||||
export const WIKI_MAINTAINER_SKILL_CANONICAL_KEY = canonicalSkillKey(WIKI_MAINTAINER_SKILL_KEY);
|
||||
export const WIKI_MANAGED_SKILL_CANONICAL_KEYS = WIKI_MANAGED_SKILL_KEYS.map(canonicalSkillKey);
|
||||
|
||||
const CURSOR_WINDOW_ROUTINE_DESCRIPTION = `Process bounded Paperclip issue-history windows into the LLM Wiki.
|
||||
|
||||
Run procedure:
|
||||
Target space: default (slug: default). Paperclip-derived indexing currently writes only into the default space, so this routine never sweeps other spaces. Per-space Paperclip ingestion profiles are a later phase; until they ship, treat any prompt to operate on a non-default space here as a bug and stop.
|
||||
1. Resolve the configured wiki root, then read the default space AGENTS.md, wiki/index.md, and the recent entries in wiki/log.md.
|
||||
2. Review recent Paperclip issue, comment, and document activity for non-plugin-operation work. Skip LLM Wiki operation issues so routine output does not feed back into itself.
|
||||
3. Synthesize Paperclip project state into wiki/projects/<slug>/standup.md for the executive current-state view, then durable project or root-issue knowledge into focused pages under wiki/projects/<slug>/index.md, wiki/concepts/, or wiki/synthesis/. Keep transient run logs out of durable pages unless they change the project's state or decisions.
|
||||
4. Write project material as concept-grouped executive synthesis. Link readable issue identifiers when useful, but do not turn project pages into issue-ID lists, UUID dumps, date ledgers, or metadata reports. Always pass wikiId \`default\` and spaceSlug \`default\` to LLM Wiki tools.
|
||||
5. Refresh wiki/index.md and append a short wiki/log.md entry listing the source window, affected pages, skipped windows, warnings, and any follow-up issue needed.
|
||||
6. If there is no new durable signal, record that in wiki/log.md and close the routine issue with a concise note.`;
|
||||
|
||||
const NIGHTLY_LINT_ROUTINE_DESCRIPTION = `Lint the LLM Wiki for structure, provenance, and stale synthesis.
|
||||
|
||||
Run procedure:
|
||||
Target space: default (slug: default). Paperclip-derived indexing currently writes only into the default space, so this routine never sweeps other spaces. Per-space Paperclip ingestion profiles are a later phase; until they ship, treat any prompt to operate on a non-default space here as a bug and stop.
|
||||
1. Resolve the configured wiki root, then read the default space AGENTS.md, wiki/index.md, wiki/log.md, and the current page list.
|
||||
2. Check for orphan pages, missing backlinks, stale source provenance, weak citations, duplicate concepts, contradictory claims, and index/log drift.
|
||||
3. Inspect the relevant wiki pages and raw sources before changing content. Do not invent missing provenance.
|
||||
4. Apply low-risk fixes directly: refresh backlinks, repair index entries, add missing source links, and append a wiki/log.md lint entry. Always pass wikiId \`default\` and spaceSlug \`default\` to LLM Wiki tools.
|
||||
5. For ambiguous contradictions or major rewrites, leave the pages unchanged and create or comment a follow-up Paperclip issue with the exact files and evidence.
|
||||
6. Close the routine issue with counts by severity, files changed, and unresolved findings.`;
|
||||
|
||||
const INDEX_REFRESH_ROUTINE_DESCRIPTION = `Refresh the LLM Wiki navigation and change log.
|
||||
|
||||
Run procedure:
|
||||
Target space: default (slug: default). Paperclip-derived indexing currently writes only into the default space, so this routine never sweeps other spaces. Per-space Paperclip ingestion profiles are a later phase; until they ship, treat any prompt to operate on a non-default space here as a bug and stop.
|
||||
1. Resolve the configured wiki root, then read the default space AGENTS.md, wiki/index.md, wiki/log.md, and the current page list.
|
||||
2. Rebuild wiki/index.md so it lists current wiki pages by category with concise summaries and valid wikilinks, and attaches wiki/projects/<slug>/standup.md links to matching project entries.
|
||||
3. Verify recently changed wiki pages and project standups are present in the index and that removed or renamed pages no longer appear.
|
||||
4. Do not rewrite content pages unless a broken title or link prevents the index from being accurate. Always pass wikiId \`default\` and spaceSlug \`default\` to LLM Wiki tools.
|
||||
5. Append a wiki/log.md entry with the index refresh time, page counts by category, and any unresolved indexing problems.
|
||||
6. Close the routine issue with the index changes and any follow-up needed.`;
|
||||
|
||||
const manifest: PaperclipPluginManifestV1 = {
|
||||
id: PLUGIN_ID,
|
||||
apiVersion: 1,
|
||||
version: "0.1.0",
|
||||
displayName: "LLM Wiki",
|
||||
description: "Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.",
|
||||
author: "Paperclip",
|
||||
categories: ["automation", "ui"],
|
||||
capabilities: [
|
||||
"events.subscribe",
|
||||
"api.routes.register",
|
||||
"database.namespace.migrate",
|
||||
"database.namespace.read",
|
||||
"database.namespace.write",
|
||||
"companies.read",
|
||||
"projects.read",
|
||||
"projects.managed",
|
||||
"skills.managed",
|
||||
"issues.read",
|
||||
"issue.subtree.read",
|
||||
"issues.create",
|
||||
"issues.update",
|
||||
"issues.wakeup",
|
||||
"issues.orchestration.read",
|
||||
"issue.comments.read",
|
||||
"issue.comments.create",
|
||||
"issue.documents.read",
|
||||
"issue.documents.write",
|
||||
"agents.read",
|
||||
"agents.managed",
|
||||
"agent.sessions.create",
|
||||
"agent.sessions.list",
|
||||
"agent.sessions.send",
|
||||
"agent.sessions.close",
|
||||
"routines.managed",
|
||||
"local.folders",
|
||||
"agent.tools.register",
|
||||
"metrics.write",
|
||||
"activity.log.write",
|
||||
"plugin.state.read",
|
||||
"plugin.state.write",
|
||||
"ui.sidebar.register",
|
||||
"ui.page.register"
|
||||
],
|
||||
entrypoints: {
|
||||
worker: "./dist/worker.js",
|
||||
ui: "./dist/ui"
|
||||
},
|
||||
database: {
|
||||
namespaceSlug: "llm_wiki",
|
||||
migrationsDir: "migrations",
|
||||
coreReadTables: ["companies", "issues", "projects", "agents"]
|
||||
},
|
||||
localFolders: [
|
||||
{
|
||||
folderKey: WIKI_ROOT_FOLDER_KEY,
|
||||
displayName: "Wiki root",
|
||||
description: "Company-scoped local folder that stores raw sources, wiki pages, Paperclip project standups under wiki/projects/, AGENTS.md, IDEA.md, wiki/index.md, and wiki/log.md.",
|
||||
access: "readWrite",
|
||||
requiredDirectories: [
|
||||
"raw",
|
||||
"wiki",
|
||||
"wiki/sources",
|
||||
"wiki/projects",
|
||||
"wiki/entities",
|
||||
"wiki/concepts",
|
||||
"wiki/synthesis"
|
||||
],
|
||||
requiredFiles: ["AGENTS.md", "IDEA.md", "wiki/index.md", "wiki/log.md"]
|
||||
}
|
||||
],
|
||||
agents: [
|
||||
{
|
||||
agentKey: WIKI_MAINTAINER_AGENT_KEY,
|
||||
displayName: "Wiki Maintainer",
|
||||
role: "knowledge-maintainer",
|
||||
title: "LLM Wiki Maintainer",
|
||||
icon: "book-open",
|
||||
capabilities: "Ingests source material, maintains local wiki pages, answers cited questions, and runs wiki lint/maintenance through plugin tools.",
|
||||
adapterType: "claude_local",
|
||||
adapterPreference: ["claude_local", "codex_local", "gemini_local", "opencode_local", "cursor", "pi_local"],
|
||||
adapterConfig: {
|
||||
dangerouslySkipPermissions: false,
|
||||
dangerouslyBypassApprovalsAndSandbox: false,
|
||||
sandbox: true,
|
||||
paperclipSkillSync: {
|
||||
desiredSkills: WIKI_MANAGED_SKILL_CANONICAL_KEYS
|
||||
}
|
||||
},
|
||||
runtimeConfig: {
|
||||
modelProfiles: {
|
||||
cheap: {
|
||||
purpose: "classification, lint planning, index maintenance"
|
||||
}
|
||||
}
|
||||
},
|
||||
permissions: {
|
||||
pluginTools: [PLUGIN_ID]
|
||||
},
|
||||
status: "paused",
|
||||
budgetMonthlyCents: 0,
|
||||
instructions: {
|
||||
entryFile: "AGENTS.md",
|
||||
content: DEFAULT_AGENT_INSTRUCTIONS,
|
||||
files: DEFAULT_AGENT_INSTRUCTION_FILES,
|
||||
assetPath: "agents/wiki-maintainer"
|
||||
}
|
||||
}
|
||||
],
|
||||
projects: [
|
||||
{
|
||||
projectKey: WIKI_PROJECT_KEY,
|
||||
displayName: "LLM Wiki",
|
||||
description: "Plugin-managed inspection area for LLM Wiki ingest, query, lint, and maintenance operation issues.",
|
||||
status: "in_progress",
|
||||
color: "#2563eb"
|
||||
}
|
||||
],
|
||||
skills: [
|
||||
{
|
||||
skillKey: WIKI_MAINTAINER_SKILL_KEY,
|
||||
displayName: "LLM Wiki Maintainer",
|
||||
slug: "llm-wiki-maintainer",
|
||||
description: "Use the LLM Wiki plugin tools to maintain a cited local company wiki.",
|
||||
markdown: skillMarkdown(WIKI_MAINTAINER_SKILL_KEY)
|
||||
},
|
||||
{
|
||||
skillKey: WIKI_INGEST_SKILL_KEY,
|
||||
displayName: "Wiki Ingest",
|
||||
slug: WIKI_INGEST_SKILL_KEY,
|
||||
description: "Turn captured raw source material into cited durable LLM Wiki pages.",
|
||||
markdown: skillMarkdown(WIKI_INGEST_SKILL_KEY)
|
||||
},
|
||||
{
|
||||
skillKey: WIKI_QUERY_SKILL_KEY,
|
||||
displayName: "Wiki Query",
|
||||
slug: WIKI_QUERY_SKILL_KEY,
|
||||
description: "Answer questions from the LLM Wiki with citations and optional durable synthesis.",
|
||||
markdown: skillMarkdown(WIKI_QUERY_SKILL_KEY)
|
||||
},
|
||||
{
|
||||
skillKey: WIKI_LINT_SKILL_KEY,
|
||||
displayName: "Wiki Lint",
|
||||
slug: WIKI_LINT_SKILL_KEY,
|
||||
description: "Audit the LLM Wiki for contradictions, orphan pages, weak provenance, broken links, and missing concepts.",
|
||||
markdown: skillMarkdown(WIKI_LINT_SKILL_KEY)
|
||||
},
|
||||
{
|
||||
skillKey: PAPERCLIP_DISTILL_SKILL_KEY,
|
||||
displayName: "Paperclip Distill",
|
||||
slug: PAPERCLIP_DISTILL_SKILL_KEY,
|
||||
description: "Turn Paperclip cursor-window, distill, or backfill source bundles into wiki-insightful project knowledge.",
|
||||
markdown: skillMarkdown(PAPERCLIP_DISTILL_SKILL_KEY)
|
||||
},
|
||||
{
|
||||
skillKey: INDEX_REFRESH_SKILL_KEY,
|
||||
displayName: "Index Refresh",
|
||||
slug: INDEX_REFRESH_SKILL_KEY,
|
||||
description: "Refresh wiki/index.md so it accurately catalogs current wiki pages.",
|
||||
markdown: skillMarkdown(INDEX_REFRESH_SKILL_KEY)
|
||||
}
|
||||
],
|
||||
routines: [
|
||||
{
|
||||
routineKey: CURSOR_WINDOW_ROUTINE_KEY,
|
||||
title: "Process LLM Wiki updates",
|
||||
description: CURSOR_WINDOW_ROUTINE_DESCRIPTION,
|
||||
status: "paused",
|
||||
priority: "low",
|
||||
assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY },
|
||||
projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY },
|
||||
concurrencyPolicy: "skip_if_active",
|
||||
catchUpPolicy: "skip_missed",
|
||||
triggers: [
|
||||
{
|
||||
kind: "schedule",
|
||||
label: "Every 6 hours",
|
||||
enabled: false,
|
||||
cronExpression: "0 */6 * * *",
|
||||
timezone: "UTC",
|
||||
signingMode: null,
|
||||
replayWindowSec: null
|
||||
}
|
||||
],
|
||||
issueTemplate: {
|
||||
surfaceVisibility: "plugin_operation",
|
||||
originId: "routine:cursor-window-processing",
|
||||
billingCode: "plugin-llm-wiki:distillation"
|
||||
}
|
||||
},
|
||||
{
|
||||
routineKey: NIGHTLY_LINT_ROUTINE_KEY,
|
||||
title: "Run LLM Wiki lint",
|
||||
description: NIGHTLY_LINT_ROUTINE_DESCRIPTION,
|
||||
status: "paused",
|
||||
priority: "low",
|
||||
assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY },
|
||||
projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY },
|
||||
concurrencyPolicy: "skip_if_active",
|
||||
catchUpPolicy: "skip_missed",
|
||||
triggers: [
|
||||
{
|
||||
kind: "schedule",
|
||||
label: "Nightly",
|
||||
enabled: false,
|
||||
cronExpression: "0 3 * * *",
|
||||
timezone: "UTC",
|
||||
signingMode: null,
|
||||
replayWindowSec: null
|
||||
}
|
||||
],
|
||||
issueTemplate: {
|
||||
surfaceVisibility: "plugin_operation",
|
||||
originId: "routine:nightly-wiki-lint",
|
||||
billingCode: "plugin-llm-wiki:maintenance"
|
||||
}
|
||||
},
|
||||
{
|
||||
routineKey: INDEX_REFRESH_ROUTINE_KEY,
|
||||
title: "Refresh LLM Wiki index",
|
||||
description: INDEX_REFRESH_ROUTINE_DESCRIPTION,
|
||||
status: "paused",
|
||||
priority: "low",
|
||||
assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY },
|
||||
projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY },
|
||||
concurrencyPolicy: "skip_if_active",
|
||||
catchUpPolicy: "skip_missed",
|
||||
triggers: [
|
||||
{
|
||||
kind: "schedule",
|
||||
label: "Hourly",
|
||||
enabled: false,
|
||||
cronExpression: "0 * * * *",
|
||||
timezone: "UTC",
|
||||
signingMode: null,
|
||||
replayWindowSec: null
|
||||
}
|
||||
],
|
||||
issueTemplate: {
|
||||
surfaceVisibility: "plugin_operation",
|
||||
originId: "routine:index-refresh",
|
||||
billingCode: "plugin-llm-wiki:maintenance"
|
||||
}
|
||||
}
|
||||
],
|
||||
tools: [
|
||||
{
|
||||
name: "wiki_search",
|
||||
displayName: "Search Wiki",
|
||||
description: "Search indexed wiki page and source metadata for one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
query: { type: "string" },
|
||||
limit: { type: "number" }
|
||||
},
|
||||
required: ["companyId", "wikiId", "query"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_read_page",
|
||||
displayName: "Read Wiki Page",
|
||||
description: "Read a markdown wiki page from one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
path: { type: "string" }
|
||||
},
|
||||
required: ["companyId", "wikiId", "path"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_write_page",
|
||||
displayName: "Write Wiki Page",
|
||||
description: "Atomically write a markdown wiki page in one wiki space after plugin path validation and optional hash conflict checks. Operation agents should pass the issue's spaceSlug; omitting it uses the default space. Protected control files such as AGENTS.md and IDEA.md are excluded from agent-tool writes.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
path: { type: "string" },
|
||||
contents: { type: "string" },
|
||||
expectedHash: { type: "string" },
|
||||
summary: { type: "string" }
|
||||
},
|
||||
required: ["companyId", "wikiId", "path", "contents"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_propose_patch",
|
||||
displayName: "Propose Wiki Patch",
|
||||
description: "Return a structured proposed page write for one wiki space without changing files. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
path: { type: "string" },
|
||||
contents: { type: "string" },
|
||||
summary: { type: "string" }
|
||||
},
|
||||
required: ["companyId", "wikiId", "path", "contents"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_list_sources",
|
||||
displayName: "List Wiki Sources",
|
||||
description: "Return captured raw source metadata from one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
limit: { type: "number" }
|
||||
},
|
||||
required: ["companyId", "wikiId"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_read_source",
|
||||
displayName: "Read Wiki Source",
|
||||
description: "Read a captured raw source from one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
rawPath: { type: "string" }
|
||||
},
|
||||
required: ["companyId", "wikiId", "rawPath"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_append_log",
|
||||
displayName: "Append Wiki Log",
|
||||
description: "Append a maintenance note to one wiki space's wiki/log.md. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
entry: { type: "string" }
|
||||
},
|
||||
required: ["companyId", "wikiId", "entry"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_update_index",
|
||||
displayName: "Update Wiki Index",
|
||||
description: "Atomically replace one wiki space's wiki/index.md with optional hash conflict checks. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
contents: { type: "string" },
|
||||
expectedHash: { type: "string" }
|
||||
},
|
||||
required: ["companyId", "wikiId", "contents"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_list_backlinks",
|
||||
displayName: "List Wiki Backlinks",
|
||||
description: "Return indexed backlinks for a wiki page in one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" },
|
||||
path: { type: "string" }
|
||||
},
|
||||
required: ["companyId", "wikiId", "path"]
|
||||
}
|
||||
},
|
||||
{
|
||||
name: "wiki_list_pages",
|
||||
displayName: "List Wiki Pages",
|
||||
description: "Return the known page index from one wiki space's plugin metadata. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
companyId: { type: "string" },
|
||||
wikiId: { type: "string" },
|
||||
spaceSlug: { type: "string" }
|
||||
},
|
||||
required: ["companyId", "wikiId"]
|
||||
}
|
||||
}
|
||||
],
|
||||
apiRoutes: [
|
||||
{
|
||||
routeKey: "overview",
|
||||
method: "GET",
|
||||
path: "/overview",
|
||||
auth: "board-or-agent",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "query", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "bootstrap",
|
||||
method: "POST",
|
||||
path: "/bootstrap",
|
||||
auth: "board",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "body", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "capture-source",
|
||||
method: "POST",
|
||||
path: "/sources",
|
||||
auth: "board-or-agent",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "body", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "spaces",
|
||||
method: "GET",
|
||||
path: "/spaces",
|
||||
auth: "board-or-agent",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "query", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "create-space",
|
||||
method: "POST",
|
||||
path: "/spaces",
|
||||
auth: "board",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "body", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "update-space",
|
||||
method: "PATCH",
|
||||
path: "/spaces/:spaceSlug",
|
||||
auth: "board",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "body", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "bootstrap-space",
|
||||
method: "POST",
|
||||
path: "/spaces/:spaceSlug/bootstrap",
|
||||
auth: "board",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "body", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "archive-space",
|
||||
method: "POST",
|
||||
path: "/spaces/:spaceSlug/archive",
|
||||
auth: "board",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "body", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "operations",
|
||||
method: "GET",
|
||||
path: "/operations",
|
||||
auth: "board-or-agent",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "query", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "start-query",
|
||||
method: "POST",
|
||||
path: "/query-sessions",
|
||||
auth: "board",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "body", key: "companyId" }
|
||||
},
|
||||
{
|
||||
routeKey: "file-as-page",
|
||||
method: "POST",
|
||||
path: "/file-as-page",
|
||||
auth: "board",
|
||||
capability: "api.routes.register",
|
||||
companyResolution: { from: "body", key: "companyId" }
|
||||
}
|
||||
],
|
||||
ui: {
|
||||
slots: [
|
||||
{
|
||||
type: "sidebar",
|
||||
id: "wiki-sidebar",
|
||||
displayName: "Wiki",
|
||||
exportName: "SidebarLink",
|
||||
order: 35
|
||||
},
|
||||
{
|
||||
type: "page",
|
||||
id: "wiki-page",
|
||||
displayName: "Wiki",
|
||||
exportName: "WikiPage",
|
||||
routePath: "wiki"
|
||||
},
|
||||
{
|
||||
type: "routeSidebar",
|
||||
id: "wiki-route-sidebar",
|
||||
displayName: "Wiki",
|
||||
exportName: "WikiRouteSidebar",
|
||||
routePath: "wiki"
|
||||
}
|
||||
]
|
||||
}
|
||||
};
|
||||
|
||||
export default manifest;
|
||||
@@ -0,0 +1,73 @@
|
||||
import { readdirSync, readFileSync, statSync } from "node:fs";
|
||||
|
||||
export const REQUIRED_WIKI_DIRECTORIES = [
|
||||
"raw",
|
||||
"wiki",
|
||||
"wiki/sources",
|
||||
"wiki/projects",
|
||||
"wiki/entities",
|
||||
"wiki/concepts",
|
||||
"wiki/synthesis",
|
||||
] as const;
|
||||
|
||||
export const REQUIRED_WIKI_FILES = ["AGENTS.md", "IDEA.md", "wiki/index.md", "wiki/log.md"] as const;
|
||||
export const KARPATHY_LLM_WIKI_GIST_URL = "https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f";
|
||||
|
||||
function templateFile(path: string): string {
|
||||
return readFileSync(new URL(`../templates/${path}`, import.meta.url), "utf8");
|
||||
}
|
||||
|
||||
function agentInstructionFiles(agentKey: string): Record<string, string> {
|
||||
const root = new URL(`../agents/${agentKey}/`, import.meta.url);
|
||||
const files: Record<string, string> = {};
|
||||
|
||||
function walk(relativeDir: string) {
|
||||
const dirUrl = new URL(relativeDir ? `${relativeDir}/` : "./", root);
|
||||
for (const entry of readdirSync(dirUrl)) {
|
||||
if (entry === ".DS_Store") continue;
|
||||
const relativePath = relativeDir ? `${relativeDir}/${entry}` : entry;
|
||||
const entryUrl = new URL(relativePath, root);
|
||||
const stat = statSync(entryUrl);
|
||||
if (stat.isDirectory()) {
|
||||
walk(relativePath);
|
||||
} else if (stat.isFile()) {
|
||||
files[relativePath] = readFileSync(entryUrl, "utf8");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
walk("");
|
||||
return Object.fromEntries(Object.entries(files).sort(([left], [right]) => left.localeCompare(right)));
|
||||
}
|
||||
|
||||
export const DEFAULT_WIKI_SCHEMA = templateFile("AGENTS.md");
|
||||
export const DEFAULT_AGENT_INSTRUCTION_FILES = agentInstructionFiles("wiki-maintainer");
|
||||
export const DEFAULT_AGENT_INSTRUCTIONS = DEFAULT_AGENT_INSTRUCTION_FILES["AGENTS.md"] ?? "";
|
||||
export const DEFAULT_IDEA = templateFile("IDEA.md");
|
||||
export const DEFAULT_INDEX = templateFile("wiki/index.md");
|
||||
export const DEFAULT_LOG = templateFile("wiki/log.md");
|
||||
export const DEFAULT_GITIGNORE = templateFile(".gitignore");
|
||||
|
||||
export const QUERY_PROMPT = `Answer from the LLM Wiki using the installed wiki-query skill.
|
||||
|
||||
Read the target space's wiki/index.md first, inspect relevant pages and raw/source references in that same space, cite the wiki page paths and raw source paths used, and say when the wiki does not contain enough evidence. Useful durable synthesis should be filed back into wiki/synthesis/ inside that same space. Always pass the operation issue's wikiId and spaceSlug to LLM Wiki tools.
|
||||
`;
|
||||
|
||||
export const LINT_PROMPT = `Lint the LLM Wiki using the installed wiki-lint skill.
|
||||
|
||||
Audit the target space only for contradictions, stale claims, orphan pages, missing backlinks, weak provenance, and wiki/index.md / wiki/log.md drift. Also look for important concepts mentioned without pages and answers that should have been filed back into wiki/. Return findings grouped by severity with concrete file paths, evidence, and suggested fixes — do not auto-apply edits. Always pass the operation issue's wikiId and spaceSlug to LLM Wiki tools.
|
||||
`;
|
||||
|
||||
export const BOOTSTRAP_FILES: ReadonlyArray<{ path: string; contents: string }> = [
|
||||
{ path: ".gitignore", contents: DEFAULT_GITIGNORE },
|
||||
{ path: "AGENTS.md", contents: DEFAULT_WIKI_SCHEMA },
|
||||
{ path: "IDEA.md", contents: DEFAULT_IDEA },
|
||||
{ path: "wiki/index.md", contents: DEFAULT_INDEX },
|
||||
{ path: "wiki/log.md", contents: DEFAULT_LOG },
|
||||
{ path: "raw/.gitkeep", contents: "" },
|
||||
{ path: "wiki/sources/.gitkeep", contents: "" },
|
||||
{ path: "wiki/projects/.gitkeep", contents: "" },
|
||||
{ path: "wiki/entities/.gitkeep", contents: "" },
|
||||
{ path: "wiki/concepts/.gitkeep", contents: "" },
|
||||
{ path: "wiki/synthesis/.gitkeep", contents: "" },
|
||||
];
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1 @@
|
||||
export { SidebarLink, SettingsPage, WikiPage, WikiRouteSidebar } from "./app.js";
|
||||
@@ -0,0 +1,49 @@
|
||||
type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
|
||||
|
||||
export type IngestSourceActionResult = {
|
||||
operation?: {
|
||||
issue?: {
|
||||
id?: unknown;
|
||||
} | null;
|
||||
} | null;
|
||||
};
|
||||
|
||||
export function readIngestOperationIssueId(result: unknown): string {
|
||||
const issueId = (result as IngestSourceActionResult | null)?.operation?.issue?.id;
|
||||
if (typeof issueId === "string" && issueId.trim()) return issueId;
|
||||
throw new Error("Ingest operation did not return an issue id; the dropped file could not be attached.");
|
||||
}
|
||||
|
||||
async function readUploadError(response: Response): Promise<string> {
|
||||
const body = await response.json().catch(() => null);
|
||||
if (body && typeof body === "object") {
|
||||
const error = (body as { error?: unknown; message?: unknown }).error;
|
||||
if (typeof error === "string" && error.trim()) return error;
|
||||
const message = (body as { error?: unknown; message?: unknown }).message;
|
||||
if (typeof message === "string" && message.trim()) return message;
|
||||
}
|
||||
return `Attachment upload failed with HTTP ${response.status}.`;
|
||||
}
|
||||
|
||||
export async function uploadIssueAttachmentFile(input: {
|
||||
companyId: string;
|
||||
issueId: string;
|
||||
file: File;
|
||||
fetchImpl?: FetchLike;
|
||||
}): Promise<unknown> {
|
||||
const fetchImpl = input.fetchImpl ?? fetch;
|
||||
const form = new FormData();
|
||||
form.append("file", input.file);
|
||||
const response = await fetchImpl(
|
||||
`/api/companies/${encodeURIComponent(input.companyId)}/issues/${encodeURIComponent(input.issueId)}/attachments`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
body: form,
|
||||
},
|
||||
);
|
||||
if (!response.ok) {
|
||||
throw new Error(await readUploadError(response));
|
||||
}
|
||||
return response.json();
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
export * from "./wiki/core.js";
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,3 @@
|
||||
.DS_Store
|
||||
.obsidian/workspace*
|
||||
.obsidian/cache
|
||||
@@ -0,0 +1,137 @@
|
||||
# AGENTS.md — LLM Wiki Schema
|
||||
|
||||
You are the maintainer of this personal wiki. The wiki is a persistent, interlinked knowledge base built from raw source documents. You read sources, extract knowledge, and integrate it into evolving wiki pages. The user curates sources, directs analysis, and asks questions; you handle the bookkeeping.
|
||||
|
||||
The underlying pattern is described in `IDEA.md` (Karpathy's "LLM Wiki" gist). Read it if you need the philosophy; this file is the operational schema.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
.
|
||||
├── AGENTS.md # this file — your operating instructions
|
||||
├── IDEA.md # the pattern this wiki follows
|
||||
├── raw/ # immutable source documents (you read, never write)
|
||||
└── wiki/ # generated, owned by you
|
||||
├── index.md # catalog of all pages
|
||||
├── log.md # append-only timeline of operations
|
||||
├── sources/ # one summary page per source
|
||||
├── projects/ # Paperclip project overviews, standups, decisions, and history
|
||||
│ └── <slug>/
|
||||
│ ├── index.md
|
||||
│ ├── standup.md
|
||||
│ ├── decisions.md
|
||||
│ └── history.md
|
||||
├── entities/ # people, organizations, products, places
|
||||
├── concepts/ # ideas, frameworks, definitions
|
||||
└── synthesis/ # cross-cutting analysis, comparisons, theses
|
||||
```
|
||||
|
||||
The subdirectories under `wiki/` are conventional, not enforced. Add new categories (e.g. `wiki/papers/`) as the domain demands — and update this file when you do.
|
||||
|
||||
Paperclip project material lives only under `wiki/projects/<project-slug>/`. Do not create a top-level `projects/` directory.
|
||||
|
||||
- `wiki/projects/<project-slug>/standup.md` is the executive-level project standup. It answers where the project stands today, what changed recently, current blockers/risks, and the next concrete actions.
|
||||
- `wiki/projects/<project-slug>/index.md` is the durable knowledge page. It explains what the project is, why it exists, decisions made, history, and long-lived context.
|
||||
- Keep the two linked. A standup should link to the durable project page, and the durable project page should point at the current standup for live status.
|
||||
- Update `standup.md` whenever Paperclip project, issue, plan, comment, blocker, approval, or status history materially changes the project's current state. Do not append endless dated sections; rewrite it as today's concise status.
|
||||
- Project writing should be editorial and concept-grouped. Do not dump issue queues, UUIDs, raw metadata, or date-heavy ledgers into project pages. Reference Paperclip tasks with human issue links where useful, but make headings and paragraphs explain the concepts, decisions, completed work, next work, and blockers in plain executive language.
|
||||
|
||||
## Page conventions
|
||||
|
||||
- **Filename:** kebab-case, `.md`. Treat filenames as stable; do not rename without updating backlinks.
|
||||
- **Frontmatter:** YAML at the top of every wiki page.
|
||||
```yaml
|
||||
---
|
||||
title: Human-readable title
|
||||
type: source | project | entity | concept | synthesis
|
||||
tags: [tag-a, tag-b]
|
||||
sources: [raw/doc.pdf] # for source pages and synthesis pages
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
- **Cross-links:** Obsidian-style `[[wiki/entities/some-page]]` (or `[[some-page]]` when unambiguous). When you mention a concept or entity that has — or should have — its own page, link it.
|
||||
- **Citations:** cite the source inline whenever a claim comes from one: `(see [[wiki/sources/some-slug]])`.
|
||||
- **Voice:** terse, factual, neutral. The wiki is reference material, not narrative.
|
||||
|
||||
## Operations
|
||||
|
||||
### Ingest
|
||||
|
||||
Triggered when the user drops a file in `raw/` and asks to process it (or just says "ingest").
|
||||
|
||||
1. Read the source end to end.
|
||||
2. Briefly discuss key takeaways with the user before writing — confirm what to emphasize.
|
||||
3. Create `wiki/sources/<slug>.md`: a summary page (~300–800 words) covering the source's main claims, structure, and notable quotes or data.
|
||||
4. Update or create relevant pages in `entities/`, `concepts/`, `synthesis/`. A typical ingest touches 5–15 pages.
|
||||
5. Add any new pages to `wiki/index.md`.
|
||||
6. Append a log entry:
|
||||
```
|
||||
## [YYYY-MM-DD] ingest | <source title>
|
||||
- source: raw/<filename>
|
||||
- new pages: [[...]], [[...]]
|
||||
- updated pages: [[...]], [[...]]
|
||||
- notes: <one-line synthesis, contradiction flagged, or open question>
|
||||
```
|
||||
|
||||
When new information contradicts an existing page, do **not** silently overwrite. Flag the contradiction on the page (a `> ⚠ contradicted by [[...]] (YYYY-MM-DD)` callout) and note it in the log.
|
||||
|
||||
### Project updates
|
||||
|
||||
Triggered when Paperclip project, issue, plan, comment, blocker, or status history is distilled into the wiki.
|
||||
|
||||
1. Create or update `wiki/projects/<project-slug>/standup.md` first. Every Paperclip project represented in the wiki must have one. Keep stable sections for executive readout, what changed, decisions, blockers/risks, next actions, and links.
|
||||
2. Create or update `wiki/projects/<project-slug>/index.md` as the durable project overview. Keep stable sections for overview, current direction, workstreams, decisions, open risks/blockers, and references.
|
||||
3. Use `wiki/projects/<project-slug>/decisions.md` for accepted/rejected plans, architectural decisions, approval outcomes, and reversals when a project has enough decision history to warrant a separate page.
|
||||
4. Use `wiki/projects/<project-slug>/history.md` for compact narrative history of meaningful project movement. Group by phase or concept; do not mirror every issue comment.
|
||||
5. Always cite Paperclip source material with readable links to issue identifiers, document keys, issue documents, approvals, and raw/source pages. Do not put UUIDs in prose unless the UUID itself is the subject.
|
||||
6. Update `wiki/index.md` under Projects and append a `project` log entry to `wiki/log.md`.
|
||||
|
||||
### Query
|
||||
|
||||
The user asks a question. You:
|
||||
|
||||
1. Read `wiki/index.md` to find candidate pages.
|
||||
2. Read those pages; follow links as needed.
|
||||
3. Answer with citations back to wiki pages, and ultimately to raw sources.
|
||||
4. If the answer is substantial (a comparison, analysis, new synthesis), offer to file it under `wiki/synthesis/` so the work compounds rather than disappearing into chat history.
|
||||
|
||||
If the wiki lacks what the question needs, say so plainly and suggest sources to ingest or web searches to run.
|
||||
|
||||
### Lint
|
||||
|
||||
On request ("lint", "health check"), scan for:
|
||||
|
||||
- contradictions across pages
|
||||
- claims a newer source has superseded
|
||||
- orphan pages (not linked from `index.md` or any other page)
|
||||
- concepts mentioned in multiple places but lacking a dedicated page
|
||||
- broken `[[wiki-links]]`
|
||||
- gaps where a web search or new source would help
|
||||
|
||||
Report findings as a checklist and ask the user which to act on.
|
||||
|
||||
## index.md format
|
||||
|
||||
A catalog organized by category. Each line: `- [[path]] — one-line summary`. Keep it scannable; this is your primary navigation aid before opening pages.
|
||||
|
||||
## log.md format
|
||||
|
||||
Append new entries to the bottom. Every entry header follows:
|
||||
|
||||
```
|
||||
## [YYYY-MM-DD] <op> | <subject>
|
||||
```
|
||||
|
||||
so `grep "^## \[" wiki/log.md | tail -10` always returns recent activity. Operations: `ingest`, `query`, `lint`, `setup`, `refactor`.
|
||||
|
||||
## Customization
|
||||
|
||||
This schema is intentionally generic. As the wiki's domain becomes clear, evolve it:
|
||||
|
||||
- add domain-specific page types and subdirectories
|
||||
- adjust frontmatter fields
|
||||
- specify preferred output formats for queries (Marp slides, charts, tables)
|
||||
- record workflow preferences (one-at-a-time vs batch ingest, level of human supervision)
|
||||
|
||||
When you and the user agree on a convention, **write it into this file**. The schema is the wiki's source of truth for how the wiki is built.
|
||||
@@ -0,0 +1,75 @@
|
||||
# LLM Wiki
|
||||
|
||||
A pattern for building personal knowledge bases using LLMs.
|
||||
|
||||
This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea, but your agent will build out the specifics in collaboration with you.
|
||||
|
||||
## The core idea
|
||||
|
||||
Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation. Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up. NotebookLM, ChatGPT file uploads, and most RAG systems work this way.
|
||||
|
||||
The idea here is different. Instead of just retrieving from raw documents at query time, the LLM **incrementally builds and maintains a persistent wiki** — a structured, interlinked collection of markdown files that sits between you and the raw sources. When you add a new source, the LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims, strengthening or challenging the evolving synthesis. The knowledge is compiled once and then *kept current*, not re-derived on every query.
|
||||
|
||||
This is the key difference: **the wiki is a persistent, compounding artifact.** The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you've read. The wiki keeps getting richer with every source you add and every question you ask.
|
||||
|
||||
You never (or rarely) write the wiki yourself — the LLM writes and maintains all of it. You're in charge of sourcing, exploration, and asking the right questions. The LLM does all the grunt work — the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base actually useful over time. In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.
|
||||
|
||||
This can apply to a lot of different contexts. A few examples:
|
||||
|
||||
- **Personal**: tracking your own goals, health, psychology, self-improvement — filing journal entries, articles, podcast notes, and building up a structured picture of yourself over time.
|
||||
- **Research**: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis.
|
||||
- **Reading a book**: filing each chapter as you go, building out pages for characters, themes, plot threads, and how they connect. By the end you have a rich companion wiki. Think of fan wikis like [Tolkien Gateway](https://tolkiengateway.net/wiki/Main_Page) — thousands of interlinked pages covering characters, places, events, languages, built by a community of volunteers over years. You could build something like that personally as you read, with the LLM doing all the cross-referencing and maintenance.
|
||||
- **Business/team**: an internal wiki maintained by LLMs, fed by Slack threads, meeting transcripts, project documents, customer calls. Possibly with humans in the loop reviewing updates. The wiki stays current because the LLM does the maintenance that no one on the team wants to do.
|
||||
- **Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives** — anything where you're accumulating knowledge over time and want it organized rather than scattered.
|
||||
|
||||
## Architecture
|
||||
|
||||
There are three layers:
|
||||
|
||||
**Raw sources** — your curated collection of source documents. Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them. This is your source of truth.
|
||||
|
||||
**The wiki** — a directory of LLM-generated markdown files. Summaries, entity pages, concept pages, comparisons, an overview, a synthesis. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. You read it; the LLM writes it.
|
||||
|
||||
**The schema** — a document (e.g. AGENTS.md for Paperclip agents) that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow when ingesting sources, answering questions, or maintaining the wiki. This is the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time as you figure out what works for your domain.
|
||||
|
||||
## Operations
|
||||
|
||||
**Ingest.** You drop a new source into the raw collection and tell the LLM to process it. An example flow: the LLM reads the source, discusses key takeaways with you, writes a summary page in the wiki, updates the index, updates relevant entity and concept pages across the wiki, and appends an entry to the log. A single source might touch 10-15 wiki pages. Personally I prefer to ingest sources one at a time and stay involved — I read the summaries, check the updates, and guide the LLM on what to emphasize. But you could also batch-ingest many sources at once with less supervision. It's up to you to develop the workflow that fits your style and document it in the schema for future sessions.
|
||||
|
||||
**Query.** You ask questions against the wiki. The LLM searches for relevant pages, reads them, and synthesizes an answer with citations. Answers can take different forms depending on the question — a markdown page, a comparison table, a slide deck (Marp), a chart (matplotlib), a canvas. The important insight: **good answers can be filed back into the wiki as new pages.** A comparison you asked for, an analysis, a connection you discovered — these are valuable and shouldn't disappear into chat history. This way your explorations compound in the knowledge base just like ingested sources do.
|
||||
|
||||
**Lint.** Periodically, ask the LLM to health-check the wiki. Look for: contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references, data gaps that could be filled with a web search. The LLM is good at suggesting new questions to investigate and new sources to look for. This keeps the wiki healthy as it grows.
|
||||
|
||||
## Indexing and logging
|
||||
|
||||
Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes:
|
||||
|
||||
**index.md** is content-oriented. It's a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count. Organized by category (entities, concepts, sources, etc.). The LLM updates it on every ingest. When answering a query, the LLM reads the index first to find relevant pages, then drills into them. This works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure.
|
||||
|
||||
**log.md** is chronological. It's an append-only record of what happened and when — ingests, queries, lint passes. A useful tip: if each entry starts with a consistent prefix (e.g. `## [2026-04-02] ingest | Article Title`), the log becomes parseable with simple unix tools — `grep "^## \[" log.md | tail -5` gives you the last 5 entries. The log gives you a timeline of the wiki's evolution and helps the LLM understand what's been done recently.
|
||||
|
||||
## Optional: CLI tools
|
||||
|
||||
At some point you may want to build small tools that help the LLM operate on the wiki more efficiently. A search engine over the wiki pages is the most obvious one — at small scale the index file is enough, but as the wiki grows you want proper search. [qmd](https://github.com/tobi/qmd) is a good option: it's a local search engine for markdown files with hybrid BM25/vector search and LLM re-ranking, all on-device. It has both a CLI (so the LLM can shell out to it) and an MCP server (so the LLM can use it as a native tool). You could also build something simpler yourself — the LLM can help you vibe-code a naive search script as the need arises.
|
||||
|
||||
## Tips and tricks
|
||||
|
||||
- **Obsidian Web Clipper** is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection.
|
||||
- **Download images locally.** In Obsidian Settings → Files and links, set "Attachment folder path" to a fixed directory (e.g. `raw/assets/`). Then in Settings → Hotkeys, search for "Download" to find "Download attachments for current file" and bind it to a hotkey (e.g. Ctrl+Shift+D). After clipping an article, hit the hotkey and all images get downloaded to local disk. This is optional but useful — it lets the LLM view and reference images directly instead of relying on URLs that may break. Note that LLMs can't natively read markdown with inline images in one pass — the workaround is to have the LLM read the text first, then view some or all of the referenced images separately to gain additional context. It's a bit clunky but works well enough.
|
||||
- **Obsidian's graph view** is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans.
|
||||
- **Marp** is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content.
|
||||
- **Dataview** is an Obsidian plugin that runs queries over page frontmatter. If your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables and lists.
|
||||
- The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free.
|
||||
|
||||
## Why this works
|
||||
|
||||
The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.
|
||||
|
||||
The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else.
|
||||
|
||||
The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. Bush's vision was closer to this than to what the web became: private, actively curated, with the connections between documents as valuable as the documents themselves. The part he couldn't solve was who does the maintenance. The LLM handles that.
|
||||
|
||||
|
||||
## Note
|
||||
|
||||
This document is intentionally abstract. It describes the idea, not a specific implementation. The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice. Everything mentioned above is optional and modular — pick what's useful, ignore what isn't. For example: your sources might be text-only, so you don't need image handling at all. Your wiki might be small enough that the index file is all you need, no search engine required. You might not care about slide decks and just want markdown pages. You might want a completely different set of output formats. The right way to use this is to share it with your LLM agent and work together to instantiate a version that fits your needs. The document's only job is to communicate the pattern. Your LLM can figure out the rest.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Index
|
||||
|
||||
Catalog of durable wiki pages and linked project standups. Updated on every ingest or Paperclip distill.
|
||||
|
||||
## Sources
|
||||
|
||||
_(none yet)_
|
||||
|
||||
## Projects
|
||||
|
||||
_(none yet)_
|
||||
|
||||
## Entities
|
||||
|
||||
_(none yet)_
|
||||
|
||||
## Concepts
|
||||
|
||||
_(none yet)_
|
||||
|
||||
## Synthesis
|
||||
|
||||
_(none yet)_
|
||||
@@ -0,0 +1,10 @@
|
||||
# Log
|
||||
|
||||
Append-only chronological record of wiki operations.
|
||||
|
||||
## [2026-05-03] setup | wiki initialized
|
||||
- created `AGENTS.md` (schema)
|
||||
- created `raw/` for source documents
|
||||
- created `wiki/` skeleton: `index.md`, `log.md`, `sources/`, `projects/`, `entities/`, `concepts/`, `synthesis/`
|
||||
- created `wiki/projects/` for Paperclip project overviews and standups
|
||||
- pattern reference: `IDEA.md` (Karpathy "LLM Wiki" gist, https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
|
||||
@@ -0,0 +1,60 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { readIngestOperationIssueId, uploadIssueAttachmentFile } from "../src/ui/issue-attachments.js";
|
||||
|
||||
describe("LLM Wiki issue attachment uploads", () => {
|
||||
it("reads the ingest operation issue id from the action result", () => {
|
||||
expect(readIngestOperationIssueId({
|
||||
operation: {
|
||||
issue: {
|
||||
id: "issue-1",
|
||||
},
|
||||
},
|
||||
})).toBe("issue-1");
|
||||
});
|
||||
|
||||
it("rejects an ingest result that cannot identify the created issue", () => {
|
||||
expect(() => readIngestOperationIssueId({ operation: { issue: null } }))
|
||||
.toThrow("did not return an issue id");
|
||||
});
|
||||
|
||||
it("uploads the original file to the created ingest task", async () => {
|
||||
const file = new File(["hello"], "source notes.md", { type: "text/markdown" });
|
||||
const calls: Array<{ input: string; init: RequestInit }> = [];
|
||||
const fetchImpl = async (input: string, init: RequestInit) => {
|
||||
calls.push({ input, init });
|
||||
return new Response(JSON.stringify({ id: "attachment-1" }), {
|
||||
status: 201,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
});
|
||||
};
|
||||
|
||||
await expect(uploadIssueAttachmentFile({
|
||||
companyId: "company 1",
|
||||
issueId: "issue/1",
|
||||
file,
|
||||
fetchImpl,
|
||||
})).resolves.toEqual({ id: "attachment-1" });
|
||||
|
||||
expect(calls).toHaveLength(1);
|
||||
expect(calls[0]?.input).toBe("/api/companies/company%201/issues/issue%2F1/attachments");
|
||||
expect(calls[0]?.init.method).toBe("POST");
|
||||
expect(calls[0]?.init.credentials).toBe("include");
|
||||
const body = calls[0]?.init.body;
|
||||
expect(body).toBeInstanceOf(FormData);
|
||||
expect((body as FormData).get("file")).toBe(file);
|
||||
});
|
||||
|
||||
it("surfaces server upload errors", async () => {
|
||||
const fetchImpl = async () => new Response(JSON.stringify({ error: "Attachment exceeds 10 bytes" }), {
|
||||
status: 422,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
});
|
||||
|
||||
await expect(uploadIssueAttachmentFile({
|
||||
companyId: "company-1",
|
||||
issueId: "issue-1",
|
||||
file: new File(["hello"], "source.txt"),
|
||||
fetchImpl,
|
||||
})).rejects.toThrow("Attachment exceeds 10 bytes");
|
||||
});
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,167 @@
|
||||
#!/usr/bin/env node
|
||||
import { mkdirSync, copyFileSync, existsSync, readFileSync } from "node:fs";
|
||||
import { dirname, resolve, extname } from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
import http from "node:http";
|
||||
import esbuild from "esbuild";
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const pkgRoot = resolve(__dirname, "..", "..");
|
||||
const outDir = resolve(pkgRoot, "dist", "screenshots");
|
||||
const screensDir = resolve(pkgRoot, "screenshots");
|
||||
|
||||
mkdirSync(outDir, { recursive: true });
|
||||
mkdirSync(screensDir, { recursive: true });
|
||||
|
||||
const entry = resolve(__dirname, "entry.tsx");
|
||||
|
||||
const repoRoot = resolve(pkgRoot, "..", "..", "..");
|
||||
const reactPath = resolve(repoRoot, "node_modules/.pnpm/react@19.2.4/node_modules/react");
|
||||
const reactDomPath = resolve(repoRoot, "node_modules/.pnpm/react-dom@19.2.4_react@19.2.4/node_modules/react-dom");
|
||||
|
||||
console.log("Bundling screenshot harness…");
|
||||
await esbuild.build({
|
||||
entryPoints: [entry],
|
||||
bundle: true,
|
||||
format: "esm",
|
||||
platform: "browser",
|
||||
target: "es2022",
|
||||
outfile: resolve(outDir, "bundle.js"),
|
||||
jsx: "automatic",
|
||||
loader: { ".tsx": "tsx", ".ts": "ts" },
|
||||
define: { "process.env.NODE_ENV": '"production"' },
|
||||
logLevel: "warning",
|
||||
alias: {
|
||||
"react": reactPath,
|
||||
"react-dom": reactDomPath,
|
||||
"react-dom/client": resolve(reactDomPath, "client.js"),
|
||||
"react/jsx-runtime": resolve(reactPath, "jsx-runtime.js"),
|
||||
},
|
||||
});
|
||||
|
||||
copyFileSync(resolve(__dirname, "index.html"), resolve(outDir, "index.html"));
|
||||
|
||||
const desktopViewport = { width: 1440, height: 920 };
|
||||
const mobileViewport = { width: 390, height: 844 };
|
||||
|
||||
const desktopTargets = [
|
||||
{ slug: "01-wiki-browse", view: "wiki-sidebar", section: null },
|
||||
{ slug: "02-wiki-ingest", view: "wiki-sidebar", section: "ingest" },
|
||||
{ slug: "03-wiki-query", view: "wiki-sidebar", section: "query" },
|
||||
{ slug: "04-wiki-lint", view: "wiki-sidebar", section: "lint" },
|
||||
{ slug: "05-wiki-history", view: "wiki-sidebar", section: "history" },
|
||||
{ slug: "06-wiki-settings", view: "wiki-sidebar", section: "settings" },
|
||||
{ slug: "07-host-settings", view: "settings" },
|
||||
{ slug: "09-sidebar-link", view: "sidebar" },
|
||||
{ slug: "11-wiki-distillation-settings", view: "wiki-sidebar", section: "settings/distillation" },
|
||||
{ slug: "12-wiki-distillation-unconfigured", view: "wiki-sidebar", section: "settings/distillation", search: "unconfigured=1" },
|
||||
{ slug: "20-spaces-sidebar", view: "wiki-sidebar", section: null },
|
||||
{ slug: "21-spaces-ingest", view: "wiki-sidebar", section: "ingest" },
|
||||
{ slug: "21a-spaces-ingest-with-disclaimer", view: "wiki-sidebar", section: "ingest" },
|
||||
{ slug: "22-spaces-edit", view: "wiki-sidebar", section: "settings/spaces/team-research", scrollToText: "Paperclip ingestion" },
|
||||
{ slug: "22a-spaces-edit-default", view: "wiki-sidebar", section: "settings/spaces/default", scrollToText: "Paperclip ingestion" },
|
||||
{ slug: "23-spaces-non-default-route", view: "wiki-sidebar", section: "spaces/team-research" },
|
||||
{ slug: "24-spaces-create-modal", view: "wiki-sidebar", section: null, openCreateSpaceModal: true },
|
||||
];
|
||||
|
||||
const mobileTargets = desktopTargets
|
||||
.filter((target) => !target.openCreateSpaceModal)
|
||||
.map((target) => ({
|
||||
...target,
|
||||
slug: `mobile/${target.slug}`,
|
||||
// In the production host, the route sidebar lives in the mobile drawer.
|
||||
// The page body should therefore be checked without the desktop sidebar.
|
||||
view: target.view === "wiki-sidebar" ? "wiki" : target.view,
|
||||
viewport: mobileViewport,
|
||||
}));
|
||||
|
||||
const targets = [
|
||||
...desktopTargets.map((target) => ({ ...target, viewport: desktopViewport })),
|
||||
...mobileTargets,
|
||||
];
|
||||
|
||||
const playwrightUrl = pathToFileURL(resolve(pkgRoot, "node_modules/playwright/index.mjs")).href;
|
||||
const playwrightFallback = resolve(pkgRoot, "..", "..", "..", "node_modules", ".pnpm", "playwright@1.58.2", "node_modules", "playwright", "index.mjs");
|
||||
let playwrightModuleHref = playwrightUrl;
|
||||
if (!existsSync(resolve(pkgRoot, "node_modules/playwright/index.mjs"))) {
|
||||
if (existsSync(playwrightFallback)) {
|
||||
playwrightModuleHref = pathToFileURL(playwrightFallback).href;
|
||||
} else {
|
||||
throw new Error("Cannot locate playwright module");
|
||||
}
|
||||
}
|
||||
const { chromium } = await import(playwrightModuleHref);
|
||||
|
||||
const mimeFor = (ext) => ({
|
||||
".html": "text/html; charset=utf-8",
|
||||
".js": "application/javascript; charset=utf-8",
|
||||
".mjs": "application/javascript; charset=utf-8",
|
||||
".css": "text/css; charset=utf-8",
|
||||
".map": "application/json; charset=utf-8",
|
||||
})[ext] ?? "application/octet-stream";
|
||||
|
||||
const server = http.createServer((req, res) => {
|
||||
const url = new URL(req.url ?? "/", "http://localhost");
|
||||
const requestedPath = url.pathname === "/" ? "/index.html" : url.pathname;
|
||||
const ext = extname(requestedPath);
|
||||
const candidate = ext ? resolve(outDir, "." + requestedPath) : resolve(outDir, "./index.html");
|
||||
try {
|
||||
const body = readFileSync(candidate);
|
||||
res.writeHead(200, { "Content-Type": mimeFor(extname(candidate)) });
|
||||
res.end(body);
|
||||
} catch {
|
||||
res.writeHead(404);
|
||||
res.end("Not found: " + candidate);
|
||||
}
|
||||
});
|
||||
await new Promise((r) => server.listen(0, "127.0.0.1", r));
|
||||
const { port } = server.address();
|
||||
const baseUrl = `http://127.0.0.1:${port}`;
|
||||
|
||||
const browser = await chromium.launch({ headless: true });
|
||||
const context = await browser.newContext({ viewport: desktopViewport, deviceScaleFactor: 2 });
|
||||
const page = await context.newPage();
|
||||
page.on("console", (msg) => console.log(` [console.${msg.type()}]`, msg.text()));
|
||||
page.on("pageerror", (err) => console.error(" [pageerror]", err.message));
|
||||
|
||||
for (const target of targets) {
|
||||
const sectionPath = target.section ? `/${target.section}` : "";
|
||||
const search = target.search ? `?${target.search}` : "";
|
||||
const url = `${baseUrl}/PAP/wiki${sectionPath}${search}#${target.view}`;
|
||||
console.log(`→ rendering ${target.slug} (${url})`);
|
||||
await page.setViewportSize(target.viewport);
|
||||
await page.goto(url, { waitUntil: "networkidle" });
|
||||
await page.waitForTimeout(200);
|
||||
if (target.slug === "09-sidebar-link") {
|
||||
await page.addStyleTag({ content: "body { background: var(--sidebar); }" });
|
||||
}
|
||||
if (target.openCreateSpaceModal) {
|
||||
await page.evaluate(() => {
|
||||
const btn = document.querySelector('button[aria-label="Create space"]');
|
||||
if (!btn) throw new Error("Create space button not found in DOM");
|
||||
(btn).click();
|
||||
});
|
||||
await page.waitForSelector('[aria-labelledby="create-space-modal-title"]', { timeout: 5000 });
|
||||
await page.waitForTimeout(150);
|
||||
}
|
||||
if (target.scrollToText) {
|
||||
await page.getByText(target.scrollToText).first().scrollIntoViewIfNeeded();
|
||||
await page.waitForTimeout(100);
|
||||
}
|
||||
const outFile = resolve(screensDir, `${target.slug}.png`);
|
||||
mkdirSync(dirname(outFile), { recursive: true });
|
||||
await page.screenshot({ path: outFile, fullPage: false });
|
||||
const horizontalOverflow = await page.evaluate(() => {
|
||||
const rootOverflow = document.documentElement.scrollWidth - document.documentElement.clientWidth;
|
||||
const bodyOverflow = document.body.scrollWidth - window.innerWidth;
|
||||
return Math.max(rootOverflow, bodyOverflow);
|
||||
});
|
||||
if (horizontalOverflow > 1) {
|
||||
throw new Error(`${target.slug} has ${horizontalOverflow}px horizontal overflow at ${target.viewport.width}px`);
|
||||
}
|
||||
console.log(` saved ${outFile}`);
|
||||
}
|
||||
|
||||
await browser.close();
|
||||
server.close();
|
||||
console.log("Done. Screenshots in", screensDir);
|
||||
@@ -0,0 +1,6 @@
|
||||
import { createRoot } from "react-dom/client";
|
||||
import { App } from "./harness.js";
|
||||
|
||||
const container = document.getElementById("root");
|
||||
if (!container) throw new Error("No #root in harness host");
|
||||
createRoot(container).render(<App />);
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,84 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>LLM Wiki UI Harness</title>
|
||||
<style>
|
||||
:root {
|
||||
--background: oklch(0.145 0 0);
|
||||
--foreground: oklch(0.985 0 0);
|
||||
--card: oklch(0.205 0 0);
|
||||
--primary: oklch(0.985 0 0);
|
||||
--primary-foreground: oklch(0.205 0 0);
|
||||
--secondary: oklch(0.269 0 0);
|
||||
--secondary-foreground: oklch(0.985 0 0);
|
||||
--muted: oklch(0.269 0 0);
|
||||
--muted-foreground: oklch(0.708 0 0);
|
||||
--accent: oklch(0.269 0 0);
|
||||
--accent-foreground: oklch(0.985 0 0);
|
||||
--border: oklch(0.269 0 0);
|
||||
--input: oklch(0.269 0 0);
|
||||
--sidebar: oklch(0.145 0 0);
|
||||
}
|
||||
html, body, #root {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
height: 100%;
|
||||
background: var(--background);
|
||||
color: var(--foreground);
|
||||
font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
/* Minimal Tailwind utility shim — supports just the classes used by the */
|
||||
/* plugin's WikiRouteSidebar so the screenshot harness renders something */
|
||||
/* visually close to the production host (which compiles real Tailwind). */
|
||||
.w-60 { width: 15rem; }
|
||||
.h-full { height: 100%; }
|
||||
.min-h-0 { min-height: 0; }
|
||||
.border-r { border-right-width: 1px; border-right-style: solid; }
|
||||
.border-t { border-top-width: 1px; border-top-style: solid; }
|
||||
.border-border { border-color: var(--border); }
|
||||
.bg-background { background: var(--background); }
|
||||
.bg-accent { background: var(--accent); }
|
||||
.flex { display: flex; }
|
||||
.flex-col { flex-direction: column; }
|
||||
.flex-1 { flex: 1; }
|
||||
.items-center { align-items: center; }
|
||||
.gap-0\.5 { gap: 0.125rem; }
|
||||
.gap-1 { gap: 0.25rem; }
|
||||
.gap-1\.5 { gap: 0.375rem; }
|
||||
.gap-2 { gap: 0.5rem; }
|
||||
.gap-2\.5 { gap: 0.625rem; }
|
||||
.mb-2 { margin-bottom: 0.5rem; }
|
||||
.mb-3 { margin-bottom: 0.75rem; }
|
||||
.px-2 { padding-left: 0.5rem; padding-right: 0.5rem; }
|
||||
.px-3 { padding-left: 0.75rem; padding-right: 0.75rem; }
|
||||
.py-1 { padding-top: 0.25rem; padding-bottom: 0.25rem; }
|
||||
.py-1\.5 { padding-top: 0.375rem; padding-bottom: 0.375rem; }
|
||||
.py-2 { padding-top: 0.5rem; padding-bottom: 0.5rem; }
|
||||
.py-3 { padding-top: 0.75rem; padding-bottom: 0.75rem; }
|
||||
.shrink-0 { flex-shrink: 0; }
|
||||
.text-xs { font-size: 0.75rem; line-height: 1rem; }
|
||||
.text-sm { font-size: 0.875rem; line-height: 1.25rem; }
|
||||
.text-\[11px\] { font-size: 11px; }
|
||||
.text-\[13px\] { font-size: 13px; }
|
||||
.font-medium { font-weight: 500; }
|
||||
.font-semibold { font-weight: 600; }
|
||||
.font-bold { font-weight: 700; }
|
||||
.uppercase { text-transform: uppercase; }
|
||||
.tracking-normal { letter-spacing: 0; }
|
||||
.text-foreground { color: var(--foreground); }
|
||||
.text-foreground\/80 { color: color-mix(in oklab, var(--foreground) 80%, transparent); }
|
||||
.text-muted-foreground { color: var(--muted-foreground); }
|
||||
.truncate { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
|
||||
.rounded-md { border-radius: 0.375rem; }
|
||||
.transition-colors { transition: background-color 150ms, color 150ms; }
|
||||
.overflow-y-auto { overflow-y: auto; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="root"></div>
|
||||
<script type="module" src="/bundle.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,781 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { createElement } from "react";
|
||||
import { createRoot, type Root } from "react-dom/client";
|
||||
import { act } from "react";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { WikiPage, WikiRouteSidebar } from "../src/ui/index.js";
|
||||
|
||||
const COMPANY_ID = "11111111-1111-4111-8111-111111111111";
|
||||
const EXPANDED_STORAGE_KEY = `paperclipai.plugin-llm-wiki:route-sidebar-expanded:v2:${COMPANY_ID}`;
|
||||
|
||||
type BridgeGlobal = typeof globalThis & {
|
||||
__paperclipPluginBridge__?: {
|
||||
sdkUi?: Record<string, unknown>;
|
||||
};
|
||||
};
|
||||
|
||||
type FileTreeNodeLike = {
|
||||
name: string;
|
||||
path: string;
|
||||
kind: string;
|
||||
children?: FileTreeNodeLike[];
|
||||
};
|
||||
|
||||
type FileTreePropsLike = {
|
||||
nodes: FileTreeNodeLike[];
|
||||
selectedFile?: string | null;
|
||||
expandedPaths?: ReadonlySet<string> | readonly string[];
|
||||
onToggleDir?: (path: string) => void;
|
||||
onSelectFile?: (path: string) => void;
|
||||
};
|
||||
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
|
||||
|
||||
function createFileDragEvent(
|
||||
type: string,
|
||||
options: { files?: File[]; relatedTarget?: EventTarget | null } = {},
|
||||
) {
|
||||
const event = new Event(type, { bubbles: true, cancelable: true });
|
||||
Object.defineProperty(event, "dataTransfer", {
|
||||
value: {
|
||||
types: ["Files"],
|
||||
files: options.files ?? [],
|
||||
dropEffect: "none",
|
||||
},
|
||||
});
|
||||
Object.defineProperty(event, "relatedTarget", {
|
||||
value: options.relatedTarget ?? null,
|
||||
});
|
||||
return event;
|
||||
}
|
||||
|
||||
function toArray(paths: FileTreePropsLike["expandedPaths"]): string[] {
|
||||
if (!paths) return [];
|
||||
return Array.isArray(paths) ? [...paths] : Array.from(paths);
|
||||
}
|
||||
|
||||
function renderTreeButtons(
|
||||
nodes: FileTreeNodeLike[],
|
||||
options: Pick<FileTreePropsLike, "onSelectFile" | "onToggleDir">,
|
||||
): ReturnType<typeof createElement>[] {
|
||||
const buttons: ReturnType<typeof createElement>[] = [];
|
||||
for (const node of nodes) {
|
||||
if (node.kind === "dir") {
|
||||
buttons.push(
|
||||
createElement("button", {
|
||||
key: node.path,
|
||||
type: "button",
|
||||
"data-toggle-dir": node.path,
|
||||
onClick: () => options.onToggleDir?.(node.path),
|
||||
}, node.name),
|
||||
);
|
||||
} else {
|
||||
buttons.push(
|
||||
createElement("button", {
|
||||
key: node.path,
|
||||
type: "button",
|
||||
"data-select-file": node.path,
|
||||
onClick: () => options.onSelectFile?.(node.path),
|
||||
}, node.name),
|
||||
);
|
||||
}
|
||||
buttons.push(...renderTreeButtons(node.children ?? [], options));
|
||||
}
|
||||
return buttons;
|
||||
}
|
||||
|
||||
describe("WikiRouteSidebar", () => {
|
||||
let container: HTMLDivElement;
|
||||
let root: Root;
|
||||
let hostLocation: { pathname: string; search: string; hash: string; state?: unknown };
|
||||
let navigatedTo: { to: string; options?: unknown } | null;
|
||||
let pluginDataCalls: Array<{ key: string; params?: Record<string, unknown> }>;
|
||||
let pluginActionCalls: Array<{ key: string; params?: unknown }>;
|
||||
let spacesRefreshCount: number;
|
||||
|
||||
beforeEach(() => {
|
||||
window.localStorage.clear();
|
||||
container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
root = createRoot(container);
|
||||
hostLocation = {
|
||||
pathname: "/PAP/wiki/page/wiki/concepts/sidebar-navigation.md",
|
||||
search: "",
|
||||
hash: "",
|
||||
};
|
||||
navigatedTo = null;
|
||||
pluginDataCalls = [];
|
||||
pluginActionCalls = [];
|
||||
spacesRefreshCount = 0;
|
||||
(globalThis as BridgeGlobal).__paperclipPluginBridge__ = {
|
||||
sdkUi: {
|
||||
usePluginData: (key: string, params?: Record<string, unknown>) => {
|
||||
pluginDataCalls.push({ key, params });
|
||||
if (key === "spaces") {
|
||||
return {
|
||||
data: {
|
||||
spaces: [
|
||||
{
|
||||
id: "space-default",
|
||||
companyId: COMPANY_ID,
|
||||
wikiId: "default",
|
||||
slug: "default",
|
||||
displayName: "default",
|
||||
spaceType: "managed",
|
||||
folderMode: "managed_subfolder",
|
||||
rootFolderKey: "wiki-root",
|
||||
pathPrefix: null,
|
||||
configuredRootPath: null,
|
||||
accessScope: "shared",
|
||||
ownerUserId: null,
|
||||
ownerAgentId: null,
|
||||
teamKey: null,
|
||||
settings: {},
|
||||
status: "active",
|
||||
createdAt: null,
|
||||
updatedAt: null,
|
||||
},
|
||||
{
|
||||
id: "space-engineering",
|
||||
companyId: COMPANY_ID,
|
||||
wikiId: "default",
|
||||
slug: "engineering",
|
||||
displayName: "Engineering",
|
||||
spaceType: "managed",
|
||||
folderMode: "managed_subfolder",
|
||||
rootFolderKey: "wiki-root",
|
||||
pathPrefix: "spaces/engineering",
|
||||
configuredRootPath: null,
|
||||
accessScope: "shared",
|
||||
ownerUserId: null,
|
||||
ownerAgentId: null,
|
||||
teamKey: null,
|
||||
settings: {},
|
||||
status: "active",
|
||||
createdAt: null,
|
||||
updatedAt: null,
|
||||
},
|
||||
{
|
||||
id: "space-archived",
|
||||
companyId: COMPANY_ID,
|
||||
wikiId: "default",
|
||||
slug: "qa-team-lock",
|
||||
displayName: "QA Team Lock",
|
||||
spaceType: "managed",
|
||||
folderMode: "managed_subfolder",
|
||||
rootFolderKey: "wiki-root",
|
||||
pathPrefix: "spaces/qa-team-lock",
|
||||
configuredRootPath: null,
|
||||
accessScope: "shared",
|
||||
ownerUserId: null,
|
||||
ownerAgentId: null,
|
||||
teamKey: null,
|
||||
settings: {},
|
||||
status: "archived",
|
||||
createdAt: null,
|
||||
updatedAt: null,
|
||||
},
|
||||
],
|
||||
},
|
||||
loading: false,
|
||||
error: null,
|
||||
refresh: () => {
|
||||
spacesRefreshCount += 1;
|
||||
},
|
||||
};
|
||||
}
|
||||
if (key !== "pages") return { data: null, loading: false, error: null, refresh: () => undefined };
|
||||
return {
|
||||
data: {
|
||||
pages: [
|
||||
{
|
||||
path: "wiki/concepts/sidebar-navigation.md",
|
||||
title: "Sidebar navigation",
|
||||
pageType: "concepts",
|
||||
backlinkCount: 0,
|
||||
sourceCount: 0,
|
||||
contentHash: "abc123",
|
||||
updatedAt: new Date().toISOString(),
|
||||
},
|
||||
],
|
||||
sources: [],
|
||||
},
|
||||
loading: false,
|
||||
error: null,
|
||||
refresh: () => undefined,
|
||||
};
|
||||
},
|
||||
usePluginAction: (key: string) => async (params?: unknown) => {
|
||||
pluginActionCalls.push({ key, params });
|
||||
return {};
|
||||
},
|
||||
usePluginToast: () => () => undefined,
|
||||
useHostLocation: () => hostLocation,
|
||||
useHostNavigation: () => ({
|
||||
resolveHref: (to: string) => `/PAP${to.startsWith("/") ? to : `/${to}`}`,
|
||||
navigate: (to: string, options?: unknown) => {
|
||||
navigatedTo = { to, options };
|
||||
},
|
||||
linkProps: (to: string) => ({
|
||||
href: `/PAP${to.startsWith("/") ? to : `/${to}`}`,
|
||||
onClick: () => undefined,
|
||||
}),
|
||||
}),
|
||||
FileTree: (props: FileTreePropsLike) => createElement(
|
||||
"div",
|
||||
{
|
||||
role: "tree",
|
||||
"data-selected-file": props.selectedFile ?? "",
|
||||
"data-expanded-paths": toArray(props.expandedPaths).sort().join("|"),
|
||||
},
|
||||
renderTreeButtons(props.nodes, props),
|
||||
),
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
act(() => {
|
||||
root.unmount();
|
||||
});
|
||||
container.remove();
|
||||
window.localStorage.clear();
|
||||
delete (globalThis as BridgeGlobal).__paperclipPluginBridge__;
|
||||
});
|
||||
|
||||
it("defaults wiki categories open so local files are visible", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const tree = container.querySelector("[role='tree']") as HTMLElement;
|
||||
expect(tree.dataset.expandedPaths?.split("|")).toEqual([
|
||||
"wiki",
|
||||
"wiki/concepts",
|
||||
"wiki/entities",
|
||||
"wiki/projects",
|
||||
"wiki/sources",
|
||||
"wiki/synthesis",
|
||||
]);
|
||||
});
|
||||
|
||||
it("renders Ask before Add Content in the primary sidebar tools", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const primaryNavText = container.querySelector("nav[aria-label='Wiki primary']")?.textContent ?? "";
|
||||
expect(primaryNavText.indexOf("Ask")).toBeLessThan(primaryNavText.indexOf("Add Content"));
|
||||
});
|
||||
|
||||
it("collapses and expands the active space tree from the space row", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
expect(container.querySelector("[role='tree']")).not.toBeNull();
|
||||
|
||||
act(() => {
|
||||
(container.querySelector("[aria-label='Collapse default space']") as HTMLElement).click();
|
||||
});
|
||||
|
||||
expect(container.querySelector("[role='tree']")).toBeNull();
|
||||
|
||||
act(() => {
|
||||
(container.querySelector("[aria-label='Expand default space']") as HTMLElement).click();
|
||||
});
|
||||
|
||||
expect(container.querySelector("[role='tree']")).not.toBeNull();
|
||||
});
|
||||
|
||||
it("omits redundant shared badges beside space names", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
expect(container.textContent).not.toContain("shared");
|
||||
});
|
||||
|
||||
it("hides archived spaces from the sidebar", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
expect(container.textContent).toContain("Engineering");
|
||||
expect(container.textContent).not.toContain("QA Team Lock");
|
||||
expect(pluginDataCalls).not.toContainEqual({
|
||||
key: "pages",
|
||||
params: { companyId: COMPANY_ID, includeRaw: true, spaceSlug: "qa-team-lock" },
|
||||
});
|
||||
});
|
||||
|
||||
it("refreshes and leaves an archived active space after sidebar archive", async () => {
|
||||
hostLocation = {
|
||||
pathname: "/PAP/wiki/spaces/engineering",
|
||||
search: "",
|
||||
hash: "",
|
||||
};
|
||||
const confirm = vi.spyOn(window, "confirm").mockReturnValue(true);
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
act(() => {
|
||||
(container.querySelector("[aria-label='Engineering space menu']") as HTMLButtonElement).click();
|
||||
});
|
||||
const archiveButton = Array.from(container.querySelectorAll("button"))
|
||||
.find((button) => button.textContent?.includes("Archive space"));
|
||||
|
||||
await act(async () => {
|
||||
archiveButton?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
||||
await Promise.resolve();
|
||||
});
|
||||
|
||||
expect(pluginActionCalls).toContainEqual({
|
||||
key: "archive-space",
|
||||
params: { companyId: COMPANY_ID, spaceSlug: "engineering" },
|
||||
});
|
||||
expect(spacesRefreshCount).toBe(1);
|
||||
expect(navigatedTo).toEqual({ to: "/wiki", options: undefined });
|
||||
confirm.mockRestore();
|
||||
});
|
||||
|
||||
it("persists folder expansion client-side", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
act(() => {
|
||||
(container.querySelector("[data-toggle-dir='raw']") as HTMLButtonElement).click();
|
||||
});
|
||||
|
||||
// Toggled paths are stored under the active space slug ("default::") so
|
||||
// each space remembers its own expansion state. Legacy entries written
|
||||
// before the spaces refactor stay un-prefixed and still resolve to default.
|
||||
expect(JSON.parse(window.localStorage.getItem(EXPANDED_STORAGE_KEY) ?? "[]")).toEqual([
|
||||
"default::raw",
|
||||
"wiki",
|
||||
"wiki/concepts",
|
||||
"wiki/entities",
|
||||
"wiki/projects",
|
||||
"wiki/sources",
|
||||
"wiki/synthesis",
|
||||
]);
|
||||
|
||||
act(() => {
|
||||
root.unmount();
|
||||
});
|
||||
root = createRoot(container);
|
||||
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const tree = container.querySelector("[role='tree']") as HTMLElement;
|
||||
expect(tree.dataset.expandedPaths).toBe("raw|wiki|wiki/concepts|wiki/entities|wiki/projects|wiki/sources|wiki/synthesis");
|
||||
});
|
||||
|
||||
it("does not select a wiki-link destination from the route", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const tree = () => container.querySelector("[role='tree']") as HTMLElement;
|
||||
expect(tree().dataset.selectedFile).toBe("");
|
||||
});
|
||||
|
||||
it("keeps sidebar tree selection scoped to sidebar navigation", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const tree = () => container.querySelector("[role='tree']") as HTMLElement;
|
||||
|
||||
act(() => {
|
||||
(container.querySelector("[data-select-file='wiki/concepts/sidebar-navigation.md']") as HTMLButtonElement).click();
|
||||
});
|
||||
|
||||
expect(navigatedTo).toEqual({
|
||||
to: "/wiki/page/wiki/concepts/sidebar-navigation.md",
|
||||
options: { state: { paperclipWikiSidebarTreePath: "wiki/concepts/sidebar-navigation.md" } },
|
||||
});
|
||||
// The default space stays the active space, so its tree is rendered in the
|
||||
// sidebar; non-default spaces only render their tree once activated.
|
||||
expect(tree().dataset.selectedFile).toBe("wiki/concepts/sidebar-navigation.md");
|
||||
|
||||
hostLocation = {
|
||||
pathname: "/PAP/wiki/page/wiki/entities/paperclip.md",
|
||||
search: "",
|
||||
hash: "",
|
||||
};
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
expect(tree().dataset.selectedFile).toBe("wiki/concepts/sidebar-navigation.md");
|
||||
|
||||
act(() => {
|
||||
(container.querySelector("[data-toggle-dir='wiki/concepts']") as HTMLButtonElement).click();
|
||||
});
|
||||
|
||||
expect(tree().dataset.selectedFile).toBe("wiki/concepts/sidebar-navigation.md");
|
||||
expect(tree().dataset.expandedPaths?.split("|")).not.toContain("wiki/concepts");
|
||||
});
|
||||
|
||||
it("warms inactive space pages so sidebar space switches have data ready", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiRouteSidebar, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
expect(pluginDataCalls).toContainEqual({
|
||||
key: "pages",
|
||||
params: { companyId: COMPANY_ID, includeRaw: true, spaceSlug: "engineering" },
|
||||
});
|
||||
expect(pluginDataCalls).toContainEqual({
|
||||
key: "page-content",
|
||||
params: { companyId: COMPANY_ID, path: "wiki/concepts/sidebar-navigation.md", spaceSlug: "engineering" },
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("WikiPage", () => {
|
||||
let container: HTMLDivElement;
|
||||
let root: Root;
|
||||
let consoleError: ReturnType<typeof vi.spyOn>;
|
||||
let hostLocation: { pathname: string; search: string; hash: string };
|
||||
let navigatedTo: string | null;
|
||||
|
||||
beforeEach(() => {
|
||||
container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
root = createRoot(container);
|
||||
consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
|
||||
hostLocation = {
|
||||
pathname: "/PAP/wiki/page/wiki/projects/control-plane/index.md",
|
||||
search: "",
|
||||
hash: "",
|
||||
};
|
||||
navigatedTo = null;
|
||||
(globalThis as BridgeGlobal).__paperclipPluginBridge__ = {
|
||||
sdkUi: {
|
||||
usePluginData: (key: string) => {
|
||||
if (key === "overview") {
|
||||
return {
|
||||
data: { folder: { healthy: true }, wikiId: "default" },
|
||||
loading: false,
|
||||
error: null,
|
||||
refresh: () => undefined,
|
||||
};
|
||||
}
|
||||
if (key === "spaces") {
|
||||
return {
|
||||
data: {
|
||||
spaces: [
|
||||
{
|
||||
id: "space-default",
|
||||
companyId: COMPANY_ID,
|
||||
wikiId: "default",
|
||||
slug: "default",
|
||||
displayName: "default",
|
||||
spaceType: "managed",
|
||||
folderMode: "managed_subfolder",
|
||||
rootFolderKey: "wiki-root",
|
||||
pathPrefix: null,
|
||||
configuredRootPath: null,
|
||||
accessScope: "shared",
|
||||
ownerUserId: null,
|
||||
ownerAgentId: null,
|
||||
teamKey: null,
|
||||
settings: {},
|
||||
status: "active",
|
||||
createdAt: null,
|
||||
updatedAt: null,
|
||||
},
|
||||
],
|
||||
},
|
||||
loading: false,
|
||||
error: null,
|
||||
refresh: () => undefined,
|
||||
};
|
||||
}
|
||||
if (key === "settings") {
|
||||
return {
|
||||
data: {
|
||||
folder: {
|
||||
configured: true,
|
||||
path: "/tmp/company-wiki",
|
||||
realPath: "/tmp/company-wiki",
|
||||
access: "readWrite",
|
||||
readable: true,
|
||||
writable: true,
|
||||
requiredDirectories: [],
|
||||
requiredFiles: [],
|
||||
missingDirectories: [],
|
||||
missingFiles: [],
|
||||
healthy: true,
|
||||
problems: [],
|
||||
checkedAt: new Date().toISOString(),
|
||||
},
|
||||
managedAgent: {
|
||||
status: "resolved",
|
||||
source: "managed",
|
||||
agentId: "agent-1",
|
||||
resourceKey: "wiki-maintainer",
|
||||
details: { name: "Wiki Maintainer", status: "idle", adapterType: "claude_local", icon: "book-open", urlKey: "wiki-maintainer" },
|
||||
},
|
||||
managedProject: {
|
||||
status: "resolved",
|
||||
source: "managed",
|
||||
projectId: "project-1",
|
||||
resourceKey: "llm-wiki",
|
||||
details: { name: "LLM Wiki", status: "in_progress" },
|
||||
},
|
||||
managedSkills: [],
|
||||
managedRoutines: [],
|
||||
eventIngestion: {
|
||||
enabled: false,
|
||||
sources: { issues: false, comments: false, documents: false },
|
||||
wikiId: "default",
|
||||
maxCharacters: 12000,
|
||||
},
|
||||
agentOptions: [{ id: "agent-1", name: "Wiki Maintainer", status: "idle", icon: "book-open", urlKey: "wiki-maintainer" }],
|
||||
projectOptions: [{ id: "project-1", name: "LLM Wiki", status: "in_progress", color: "#2563eb" }],
|
||||
capabilities: [],
|
||||
},
|
||||
loading: false,
|
||||
error: null,
|
||||
refresh: () => undefined,
|
||||
};
|
||||
}
|
||||
if (key === "pages") {
|
||||
return {
|
||||
data: {
|
||||
pages: [
|
||||
{
|
||||
path: "wiki/projects/control-plane/index.md",
|
||||
title: "Control plane",
|
||||
pageType: "projects",
|
||||
backlinkCount: 0,
|
||||
sourceCount: 1,
|
||||
contentHash: "abc123",
|
||||
updatedAt: new Date().toISOString(),
|
||||
},
|
||||
],
|
||||
sources: [],
|
||||
},
|
||||
loading: false,
|
||||
error: null,
|
||||
refresh: () => undefined,
|
||||
};
|
||||
}
|
||||
if (key === "page-content") {
|
||||
return {
|
||||
data: {
|
||||
wikiId: "default",
|
||||
path: "wiki/projects/control-plane/index.md",
|
||||
contents: "# Control plane\n\nCurrent project state.",
|
||||
title: "Control plane",
|
||||
pageType: "projects",
|
||||
backlinks: [],
|
||||
sourceRefs: [
|
||||
{
|
||||
kind: "issue",
|
||||
title: "Distillation kickoff",
|
||||
issueId: "issue-1",
|
||||
projectId: "project-1",
|
||||
updatedAt: "2026-05-04T15:01:00Z",
|
||||
issueIdentifier: "PAP-3416",
|
||||
},
|
||||
],
|
||||
updatedAt: "2026-05-04T15:01:00Z",
|
||||
hash: "def456",
|
||||
},
|
||||
loading: false,
|
||||
error: null,
|
||||
refresh: () => undefined,
|
||||
};
|
||||
}
|
||||
if (key === "distillation-page-provenance") {
|
||||
return { data: null, loading: false, error: null, refresh: () => undefined };
|
||||
}
|
||||
return { data: null, loading: false, error: null, refresh: () => undefined };
|
||||
},
|
||||
usePluginAction: () => async () => ({}),
|
||||
usePluginToast: () => () => undefined,
|
||||
useHostLocation: () => hostLocation,
|
||||
useHostNavigation: () => ({
|
||||
resolveHref: (to: string) => `/PAP${to.startsWith("/") ? to : `/${to}`}`,
|
||||
navigate: (to: string) => {
|
||||
navigatedTo = to;
|
||||
},
|
||||
linkProps: (to: string) => ({
|
||||
href: `/PAP${to.startsWith("/") ? to : `/${to}`}`,
|
||||
onClick: () => undefined,
|
||||
}),
|
||||
}),
|
||||
MarkdownBlock: ({ content }: { content: string }) => createElement("div", {}, content),
|
||||
MarkdownEditor: ({ value }: { value: string }) => createElement("textarea", { value, readOnly: true }),
|
||||
AssigneePicker: () => createElement("div", { "data-testid": "assignee-picker" }),
|
||||
ProjectPicker: () => createElement("div", { "data-testid": "project-picker" }),
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
act(() => {
|
||||
root.unmount();
|
||||
});
|
||||
container.remove();
|
||||
consoleError.mockRestore();
|
||||
delete (globalThis as BridgeGlobal).__paperclipPluginBridge__;
|
||||
});
|
||||
|
||||
it("renders structured Paperclip source refs as text", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiPage, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
expect(container.textContent).toContain("PAP-3416 issue - Distillation kickoff");
|
||||
const consoleOutput = consoleError.mock.calls.flat().join("\n");
|
||||
expect(consoleOutput).not.toContain("Objects are not valid as a React child");
|
||||
expect(consoleOutput).not.toContain("Each child in a list should have a unique \"key\" prop");
|
||||
});
|
||||
|
||||
it("prioritizes file drop on the ingest page without recent ingest or cost copy", () => {
|
||||
hostLocation = {
|
||||
pathname: "/PAP/wiki/ingest",
|
||||
search: "",
|
||||
hash: "",
|
||||
};
|
||||
|
||||
act(() => {
|
||||
root.render(createElement(WikiPage, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const text = container.textContent ?? "";
|
||||
expect(text).toContain("Drop files anywhere on this page");
|
||||
expect(text).not.toContain("Recent ingests");
|
||||
expect(text).not.toContain("Why does this take a moment?");
|
||||
expect(text).not.toContain("est. cost");
|
||||
|
||||
const separatorText = container.querySelector("[data-testid='llm-wiki-ingest-manual-separator']")?.textContent ?? "";
|
||||
expect(separatorText).toBe("or");
|
||||
expect(text.indexOf("Drop files anywhere on this page")).toBeLessThan(text.indexOf("Source title"));
|
||||
expect(text.indexOf("Source title")).toBeLessThan(text.indexOf("URL"));
|
||||
expect(text.indexOf("URL")).toBeLessThan(text.indexOf("Paste markdown / text"));
|
||||
});
|
||||
|
||||
it("closes the page drop overlay when a file drag leaves without dropping files", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiPage, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const page = container.querySelector("main") as HTMLElement;
|
||||
act(() => {
|
||||
page.dispatchEvent(createFileDragEvent("dragenter"));
|
||||
});
|
||||
|
||||
expect(container.querySelector("[data-testid='llm-wiki-page-drop-overlay']")).not.toBeNull();
|
||||
|
||||
act(() => {
|
||||
page.dispatchEvent(createFileDragEvent("dragleave"));
|
||||
});
|
||||
|
||||
expect(container.querySelector("[data-testid='llm-wiki-page-drop-overlay']")).toBeNull();
|
||||
expect(container.querySelector("[data-testid='llm-wiki-ingest-modal']")).toBeNull();
|
||||
});
|
||||
|
||||
it("keeps staged dropped files in the ingest modal after the drop overlay clears", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiPage, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const page = container.querySelector("main") as HTMLElement;
|
||||
const file = new File(["source notes"], "source-notes.md", { type: "text/markdown" });
|
||||
|
||||
act(() => {
|
||||
page.dispatchEvent(createFileDragEvent("dragenter"));
|
||||
page.dispatchEvent(createFileDragEvent("drop", { files: [file] }));
|
||||
});
|
||||
|
||||
expect(container.querySelector("[data-testid='llm-wiki-page-drop-overlay']")).toBeNull();
|
||||
expect(container.querySelector("[data-testid='llm-wiki-ingest-modal']")).not.toBeNull();
|
||||
expect(container.textContent).toContain("source-notes.md");
|
||||
});
|
||||
|
||||
it("lets users close the page drop overlay directly", () => {
|
||||
act(() => {
|
||||
root.render(createElement(WikiPage, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
const page = container.querySelector("main") as HTMLElement;
|
||||
act(() => {
|
||||
page.dispatchEvent(createFileDragEvent("dragenter"));
|
||||
});
|
||||
|
||||
const closeButton = container.querySelector("[aria-label='Close ingest drop overlay']") as HTMLButtonElement;
|
||||
expect(closeButton).not.toBeNull();
|
||||
|
||||
act(() => {
|
||||
closeButton.click();
|
||||
});
|
||||
|
||||
expect(container.querySelector("[data-testid='llm-wiki-page-drop-overlay']")).toBeNull();
|
||||
});
|
||||
|
||||
it("navigates settings tabs to their URL subpaths", () => {
|
||||
hostLocation = {
|
||||
pathname: "/PAP/wiki/settings",
|
||||
search: "",
|
||||
hash: "",
|
||||
};
|
||||
|
||||
act(() => {
|
||||
root.render(createElement(WikiPage, {
|
||||
context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
|
||||
} as never));
|
||||
});
|
||||
|
||||
act(() => {
|
||||
(Array.from(container.querySelectorAll("button")).find((button) => button.textContent?.includes("Distillation")) as HTMLButtonElement).click();
|
||||
});
|
||||
|
||||
expect(navigatedTo).toBe("/wiki/settings/distillation");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,27 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"lib": [
|
||||
"ES2022",
|
||||
"DOM"
|
||||
],
|
||||
"jsx": "react-jsx",
|
||||
"strict": true,
|
||||
"skipLibCheck": true,
|
||||
"declaration": true,
|
||||
"declarationMap": true,
|
||||
"sourceMap": true,
|
||||
"outDir": "dist",
|
||||
"rootDir": "."
|
||||
},
|
||||
"include": [
|
||||
"src",
|
||||
"tests"
|
||||
],
|
||||
"exclude": [
|
||||
"dist",
|
||||
"node_modules"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
import { defineConfig } from "vitest/config";
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
include: ["tests/**/*.spec.ts"],
|
||||
environment: "node",
|
||||
},
|
||||
});
|
||||
@@ -420,6 +420,12 @@ export interface ManagedRoutineMissingRef {
|
||||
resourceKey: string;
|
||||
}
|
||||
|
||||
export interface ManagedRoutineDefaultDrift {
|
||||
changedFields: string[];
|
||||
defaultTitle?: string | null;
|
||||
defaultDescription?: string | null;
|
||||
}
|
||||
|
||||
export interface ManagedRoutinesListItem {
|
||||
key: string;
|
||||
title: string;
|
||||
@@ -434,6 +440,7 @@ export interface ManagedRoutinesListItem {
|
||||
lastRunStatus?: string | null;
|
||||
managedByPluginDisplayName?: string | null;
|
||||
missingRefs?: ManagedRoutineMissingRef[];
|
||||
defaultDrift?: ManagedRoutineDefaultDrift | null;
|
||||
}
|
||||
|
||||
export interface ManagedRoutinesListProps {
|
||||
|
||||
@@ -34,6 +34,7 @@
|
||||
* @see PLUGIN_SPEC.md §14 — SDK Surface
|
||||
*/
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { createInterface, type Interface as ReadlineInterface } from "node:readline";
|
||||
import { fileURLToPath } from "node:url";
|
||||
@@ -175,6 +176,21 @@ interface EventRegistration {
|
||||
/** Default timeout for worker→host RPC calls. */
|
||||
const DEFAULT_RPC_TIMEOUT_MS = 30_000;
|
||||
|
||||
function realpathOrResolvedPath(filePath: string): string {
|
||||
const resolvedPath = path.resolve(filePath);
|
||||
try {
|
||||
return fs.realpathSync.native(resolvedPath);
|
||||
} catch {
|
||||
return resolvedPath;
|
||||
}
|
||||
}
|
||||
|
||||
export function isWorkerEntrypoint(entry: string, moduleUrl: string): boolean {
|
||||
const thisFile = realpathOrResolvedPath(fileURLToPath(moduleUrl));
|
||||
const entryPath = realpathOrResolvedPath(entry);
|
||||
return thisFile === entryPath;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// startWorkerRpcHost
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -223,9 +239,7 @@ export function runWorker(
|
||||
}
|
||||
const entry = process.argv[1];
|
||||
if (typeof entry !== "string") return;
|
||||
const thisFile = path.resolve(fileURLToPath(moduleUrl));
|
||||
const entryPath = path.resolve(entry);
|
||||
if (thisFile === entryPath) {
|
||||
if (isWorkerEntrypoint(entry, moduleUrl)) {
|
||||
startWorkerRpcHost({ plugin });
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
import fs from "node:fs";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
import { isWorkerEntrypoint } from "../src/worker-rpc-host.js";
|
||||
|
||||
describe("isWorkerEntrypoint", () => {
|
||||
const tempRoots: string[] = [];
|
||||
|
||||
afterEach(() => {
|
||||
for (const tempRoot of tempRoots.splice(0)) {
|
||||
fs.rmSync(tempRoot, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
function createTempRoot(): string {
|
||||
const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-sdk-worker-"));
|
||||
tempRoots.push(tempRoot);
|
||||
return tempRoot;
|
||||
}
|
||||
|
||||
it("matches an entrypoint reached through a symlinked directory", () => {
|
||||
const tempRoot = createTempRoot();
|
||||
const realDir = path.join(tempRoot, "real");
|
||||
const linkDir = path.join(tempRoot, "link");
|
||||
fs.mkdirSync(realDir);
|
||||
fs.symlinkSync(realDir, linkDir, "dir");
|
||||
|
||||
const workerPath = path.join(realDir, "worker.js");
|
||||
fs.writeFileSync(workerPath, "");
|
||||
|
||||
expect(
|
||||
isWorkerEntrypoint(
|
||||
path.join(linkDir, "worker.js"),
|
||||
pathToFileURL(workerPath).toString(),
|
||||
),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("does not match a different entrypoint", () => {
|
||||
const tempRoot = createTempRoot();
|
||||
const workerPath = path.join(tempRoot, "worker.js");
|
||||
const otherPath = path.join(tempRoot, "other.js");
|
||||
fs.writeFileSync(workerPath, "");
|
||||
fs.writeFileSync(otherPath, "");
|
||||
|
||||
expect(
|
||||
isWorkerEntrypoint(
|
||||
otherPath,
|
||||
pathToFileURL(workerPath).toString(),
|
||||
),
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,8 @@
|
||||
import { defineConfig } from "vitest/config";
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: "node",
|
||||
include: ["tests/**/*.test.ts"],
|
||||
},
|
||||
});
|
||||
@@ -215,6 +215,40 @@ export type IssueOriginKind = BuiltInIssueOriginKind | PluginIssueOriginKind;
|
||||
export const ISSUE_SURFACE_VISIBILITIES = ["default", "plugin_operation"] as const;
|
||||
export type IssueSurfaceVisibility = (typeof ISSUE_SURFACE_VISIBILITIES)[number];
|
||||
|
||||
export const ISSUE_RECOVERY_ACTION_KINDS = [
|
||||
"missing_disposition",
|
||||
"stranded_assigned_issue",
|
||||
"active_run_watchdog",
|
||||
"issue_graph_liveness",
|
||||
] as const;
|
||||
export type IssueRecoveryActionKind = (typeof ISSUE_RECOVERY_ACTION_KINDS)[number];
|
||||
|
||||
export const ISSUE_RECOVERY_ACTION_STATUSES = [
|
||||
"active",
|
||||
"escalated",
|
||||
"resolved",
|
||||
"cancelled",
|
||||
] as const;
|
||||
export type IssueRecoveryActionStatus = (typeof ISSUE_RECOVERY_ACTION_STATUSES)[number];
|
||||
|
||||
export const ISSUE_RECOVERY_ACTION_OWNER_TYPES = [
|
||||
"agent",
|
||||
"user",
|
||||
"board",
|
||||
"system",
|
||||
] as const;
|
||||
export type IssueRecoveryActionOwnerType = (typeof ISSUE_RECOVERY_ACTION_OWNER_TYPES)[number];
|
||||
|
||||
export const ISSUE_RECOVERY_ACTION_OUTCOMES = [
|
||||
"restored",
|
||||
"delegated",
|
||||
"false_positive",
|
||||
"blocked",
|
||||
"escalated",
|
||||
"cancelled",
|
||||
] as const;
|
||||
export type IssueRecoveryActionOutcome = (typeof ISSUE_RECOVERY_ACTION_OUTCOMES)[number];
|
||||
|
||||
export function pluginOperationIssueOriginKind(pluginKey: string): PluginIssueOriginKind {
|
||||
return `plugin:${pluginKey}:operation`;
|
||||
}
|
||||
|
||||
@@ -31,6 +31,10 @@ export {
|
||||
ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES,
|
||||
ISSUE_ORIGIN_KINDS,
|
||||
ISSUE_SURFACE_VISIBILITIES,
|
||||
ISSUE_RECOVERY_ACTION_KINDS,
|
||||
ISSUE_RECOVERY_ACTION_STATUSES,
|
||||
ISSUE_RECOVERY_ACTION_OWNER_TYPES,
|
||||
ISSUE_RECOVERY_ACTION_OUTCOMES,
|
||||
pluginOperationIssueOriginKind,
|
||||
isPluginOperationIssueOriginKind,
|
||||
ISSUE_RELATION_TYPES,
|
||||
@@ -149,6 +153,10 @@ export {
|
||||
type PluginIssueOriginKind,
|
||||
type IssueOriginKind,
|
||||
type IssueSurfaceVisibility,
|
||||
type IssueRecoveryActionKind,
|
||||
type IssueRecoveryActionStatus,
|
||||
type IssueRecoveryActionOwnerType,
|
||||
type IssueRecoveryActionOutcome,
|
||||
type IssueRelationType,
|
||||
type IssueTreeControlMode,
|
||||
type IssueTreeHoldReleasePolicyStrategy,
|
||||
@@ -371,8 +379,18 @@ export type {
|
||||
IssueBlockerAttention,
|
||||
IssueBlockerAttentionReason,
|
||||
IssueBlockerAttentionState,
|
||||
IssueInboxAttentionKind,
|
||||
IssueBlockedInboxAction,
|
||||
IssueBlockedInboxAttention,
|
||||
IssueBlockedInboxIssueRef,
|
||||
IssueBlockedInboxOwner,
|
||||
IssueBlockedInboxOwnerType,
|
||||
IssueBlockedInboxReason,
|
||||
IssueBlockedInboxSeverity,
|
||||
IssueBlockedInboxState,
|
||||
IssueProductivityReview,
|
||||
IssueProductivityReviewTrigger,
|
||||
IssueRecoveryAction,
|
||||
SuccessfulRunHandoffState,
|
||||
SuccessfulRunHandoffStateKind,
|
||||
IssueScheduledRetry,
|
||||
@@ -753,9 +771,15 @@ export {
|
||||
createChildIssueSchema,
|
||||
resolveCreateIssueStatusDefault,
|
||||
createIssueLabelSchema,
|
||||
issueBlockedInboxAttentionSchema,
|
||||
issueBlockedInboxIssueRefSchema,
|
||||
issueBlockedInboxReasonSchema,
|
||||
issueBlockedInboxSeveritySchema,
|
||||
issueBlockedInboxStateSchema,
|
||||
updateIssueSchema,
|
||||
issueExecutionPolicySchema,
|
||||
issueExecutionStateSchema,
|
||||
resolveIssueRecoveryActionSchema,
|
||||
issueReviewRequestSchema,
|
||||
issueExecutionWorkspaceSettingsSchema,
|
||||
checkoutIssueSchema,
|
||||
@@ -815,6 +839,7 @@ export {
|
||||
type CreateChildIssue,
|
||||
type CreateIssueLabel,
|
||||
type UpdateIssue,
|
||||
type ResolveIssueRecoveryAction,
|
||||
type CheckoutIssue,
|
||||
type AddIssueComment,
|
||||
type CreateIssueThreadInteraction,
|
||||
|
||||
@@ -149,8 +149,18 @@ export type {
|
||||
IssueBlockerAttention,
|
||||
IssueBlockerAttentionReason,
|
||||
IssueBlockerAttentionState,
|
||||
IssueInboxAttentionKind,
|
||||
IssueBlockedInboxAction,
|
||||
IssueBlockedInboxAttention,
|
||||
IssueBlockedInboxIssueRef,
|
||||
IssueBlockedInboxOwner,
|
||||
IssueBlockedInboxOwnerType,
|
||||
IssueBlockedInboxReason,
|
||||
IssueBlockedInboxSeverity,
|
||||
IssueBlockedInboxState,
|
||||
IssueProductivityReview,
|
||||
IssueProductivityReviewTrigger,
|
||||
IssueRecoveryAction,
|
||||
SuccessfulRunHandoffState,
|
||||
SuccessfulRunHandoffStateKind,
|
||||
IssueScheduledRetry,
|
||||
|
||||
@@ -15,6 +15,10 @@ import type {
|
||||
IssueExecutionStateStatus,
|
||||
IssueOriginKind,
|
||||
IssuePriority,
|
||||
IssueRecoveryActionKind,
|
||||
IssueRecoveryActionOutcome,
|
||||
IssueRecoveryActionOwnerType,
|
||||
IssueRecoveryActionStatus,
|
||||
IssueWorkMode,
|
||||
ModelProfileKey,
|
||||
IssueThreadInteractionContinuationPolicy,
|
||||
@@ -131,6 +135,7 @@ export interface IssueRelationIssueSummary {
|
||||
assigneeAgentId: string | null;
|
||||
assigneeUserId: string | null;
|
||||
terminalBlockers?: IssueRelationIssueSummary[];
|
||||
activeRecoveryAction?: IssueRecoveryAction | null;
|
||||
}
|
||||
|
||||
export type IssueBlockerAttentionState = "none" | "covered" | "stalled" | "needs_attention";
|
||||
@@ -153,6 +158,75 @@ export interface IssueBlockerAttention {
|
||||
sampleStalledBlockerIdentifier: string | null;
|
||||
}
|
||||
|
||||
export type IssueInboxAttentionKind = "blocked";
|
||||
|
||||
export type IssueBlockedInboxState =
|
||||
| "needs_attention"
|
||||
| "awaiting_decision"
|
||||
| "external_wait"
|
||||
| "recovery_open"
|
||||
| "missing_disposition";
|
||||
|
||||
export type IssueBlockedInboxSeverity = "critical" | "high" | "medium" | "low";
|
||||
|
||||
export type IssueBlockedInboxReason =
|
||||
| "blocked_by_unassigned_issue"
|
||||
| "blocked_by_assigned_backlog_issue"
|
||||
| "blocked_by_uninvokable_assignee"
|
||||
| "blocked_by_cancelled_issue"
|
||||
| "blocked_chain_stalled"
|
||||
| "invalid_review_participant"
|
||||
| "in_review_without_action_path"
|
||||
| "missing_successful_run_disposition"
|
||||
| "pending_board_decision"
|
||||
| "pending_user_decision"
|
||||
| "external_owner_action"
|
||||
| "open_recovery_issue";
|
||||
|
||||
export type IssueBlockedInboxOwnerType = "agent" | "user" | "board" | "external" | "unknown";
|
||||
|
||||
export interface IssueBlockedInboxIssueRef {
|
||||
id: string;
|
||||
identifier: string | null;
|
||||
title: string;
|
||||
status: IssueStatus;
|
||||
priority: IssuePriority;
|
||||
assigneeAgentId: string | null;
|
||||
assigneeUserId: string | null;
|
||||
}
|
||||
|
||||
export interface IssueBlockedInboxOwner {
|
||||
type: IssueBlockedInboxOwnerType;
|
||||
agentId: string | null;
|
||||
userId: string | null;
|
||||
label: string | null;
|
||||
}
|
||||
|
||||
export interface IssueBlockedInboxAction {
|
||||
label: string;
|
||||
detail: string | null;
|
||||
}
|
||||
|
||||
export interface IssueBlockedInboxAttention {
|
||||
kind: IssueInboxAttentionKind;
|
||||
state: IssueBlockedInboxState;
|
||||
reason: IssueBlockedInboxReason;
|
||||
severity: IssueBlockedInboxSeverity;
|
||||
stoppedSinceAt: string | null;
|
||||
owner: IssueBlockedInboxOwner;
|
||||
action: IssueBlockedInboxAction;
|
||||
sourceIssue: IssueBlockedInboxIssueRef | null;
|
||||
leafIssue: IssueBlockedInboxIssueRef | null;
|
||||
recoveryIssue: IssueBlockedInboxIssueRef | null;
|
||||
approvalId: string | null;
|
||||
interactionId: string | null;
|
||||
sampleIssueIdentifier: string | null;
|
||||
redaction: {
|
||||
externalDetailsRedacted: boolean;
|
||||
secretFieldsOmitted: true;
|
||||
};
|
||||
}
|
||||
|
||||
export type IssueProductivityReviewTrigger =
|
||||
| "no_comment_streak"
|
||||
| "long_active_duration"
|
||||
@@ -169,6 +243,35 @@ export interface IssueProductivityReview {
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
export interface IssueRecoveryAction {
|
||||
id: string;
|
||||
companyId: string;
|
||||
sourceIssueId: string;
|
||||
recoveryIssueId: string | null;
|
||||
kind: IssueRecoveryActionKind;
|
||||
status: IssueRecoveryActionStatus;
|
||||
ownerType: IssueRecoveryActionOwnerType;
|
||||
ownerAgentId: string | null;
|
||||
ownerUserId: string | null;
|
||||
previousOwnerAgentId: string | null;
|
||||
returnOwnerAgentId: string | null;
|
||||
cause: string;
|
||||
fingerprint: string;
|
||||
evidence: Record<string, unknown>;
|
||||
nextAction: string;
|
||||
wakePolicy: Record<string, unknown> | null;
|
||||
monitorPolicy: Record<string, unknown> | null;
|
||||
attemptCount: number;
|
||||
maxAttempts: number | null;
|
||||
timeoutAt: Date | string | null;
|
||||
lastAttemptAt: Date | string | null;
|
||||
outcome: IssueRecoveryActionOutcome | null;
|
||||
resolutionNote: string | null;
|
||||
resolvedAt: Date | string | null;
|
||||
createdAt: Date | string;
|
||||
updatedAt: Date | string;
|
||||
}
|
||||
|
||||
export type SuccessfulRunHandoffStateKind = "required" | "resolved" | "escalated";
|
||||
|
||||
export interface SuccessfulRunHandoffState {
|
||||
@@ -371,7 +474,9 @@ export interface Issue {
|
||||
blockedBy?: IssueRelationIssueSummary[];
|
||||
blocks?: IssueRelationIssueSummary[];
|
||||
blockerAttention?: IssueBlockerAttention;
|
||||
blockedInboxAttention?: IssueBlockedInboxAttention | null;
|
||||
productivityReview?: IssueProductivityReview | null;
|
||||
activeRecoveryAction?: IssueRecoveryAction | null;
|
||||
successfulRunHandoff?: SuccessfulRunHandoffState | null;
|
||||
scheduledRetry?: IssueScheduledRetry | null;
|
||||
relatedWork?: IssueRelatedWorkSummary;
|
||||
@@ -399,6 +504,10 @@ export interface IssueComment {
|
||||
authorType: IssueCommentAuthorType;
|
||||
authorAgentId: string | null;
|
||||
authorUserId: string | null;
|
||||
createdByRunId?: string | null;
|
||||
derivedAuthorAgentId?: string | null;
|
||||
derivedCreatedByRunId?: string | null;
|
||||
derivedAuthorSource?: "run_log_comment_post" | null;
|
||||
body: string;
|
||||
presentation: IssueCommentPresentation | null;
|
||||
metadata: IssueCommentMetadata | null;
|
||||
|
||||
@@ -155,9 +155,16 @@ export {
|
||||
createChildIssueSchema,
|
||||
resolveCreateIssueStatusDefault,
|
||||
createIssueLabelSchema,
|
||||
issueBlockedInboxAttentionSchema,
|
||||
issueBlockedInboxIssueRefSchema,
|
||||
issueBlockedInboxReasonSchema,
|
||||
issueBlockedInboxSeveritySchema,
|
||||
issueBlockedInboxStateSchema,
|
||||
updateIssueSchema,
|
||||
issueExecutionPolicySchema,
|
||||
issueExecutionStateSchema,
|
||||
issueRecoveryActionReadModelSchema,
|
||||
resolveIssueRecoveryActionSchema,
|
||||
issueReviewRequestSchema,
|
||||
issueExecutionWorkspaceSettingsSchema,
|
||||
checkoutIssueSchema,
|
||||
@@ -200,6 +207,8 @@ export {
|
||||
type CreateIssueLabel,
|
||||
type UpdateIssue,
|
||||
type IssueExecutionWorkspaceSettings,
|
||||
type IssueRecoveryActionReadModel,
|
||||
type ResolveIssueRecoveryAction,
|
||||
type CheckoutIssue,
|
||||
type AddIssueComment,
|
||||
type CreateIssueThreadInteraction,
|
||||
|
||||
@@ -3,6 +3,8 @@ import { MAX_ISSUE_REQUEST_DEPTH } from "../index.js";
|
||||
import {
|
||||
addIssueCommentSchema,
|
||||
createIssueSchema,
|
||||
issueBlockedInboxAttentionSchema,
|
||||
resolveIssueRecoveryActionSchema,
|
||||
respondIssueThreadInteractionSchema,
|
||||
suggestedTaskDraftSchema,
|
||||
updateIssueSchema,
|
||||
@@ -46,6 +48,70 @@ describe("issue validators", () => {
|
||||
expect(parsed.comment).toBe("Done\n\n- Verified the route");
|
||||
});
|
||||
|
||||
it("allows false-positive recovery resolutions to atomically restore the source issue status", () => {
|
||||
expect(
|
||||
resolveIssueRecoveryActionSchema.parse({
|
||||
outcome: "false_positive",
|
||||
sourceIssueStatus: "in_review",
|
||||
}),
|
||||
).toMatchObject({
|
||||
outcome: "false_positive",
|
||||
sourceIssueStatus: "in_review",
|
||||
});
|
||||
|
||||
expect(
|
||||
resolveIssueRecoveryActionSchema.safeParse({
|
||||
outcome: "false_positive",
|
||||
sourceIssueStatus: "blocked",
|
||||
}).success,
|
||||
).toBe(false);
|
||||
|
||||
expect(
|
||||
resolveIssueRecoveryActionSchema.safeParse({
|
||||
outcome: "false_positive",
|
||||
}).success,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("allows cancelled recovery resolutions to atomically restore the source issue status", () => {
|
||||
expect(
|
||||
resolveIssueRecoveryActionSchema.parse({
|
||||
outcome: "cancelled",
|
||||
sourceIssueStatus: "in_review",
|
||||
}),
|
||||
).toMatchObject({
|
||||
outcome: "cancelled",
|
||||
sourceIssueStatus: "in_review",
|
||||
});
|
||||
|
||||
expect(
|
||||
resolveIssueRecoveryActionSchema.safeParse({
|
||||
outcome: "cancelled",
|
||||
sourceIssueStatus: "blocked",
|
||||
}).success,
|
||||
).toBe(false);
|
||||
|
||||
expect(
|
||||
resolveIssueRecoveryActionSchema.safeParse({
|
||||
outcome: "cancelled",
|
||||
}).success,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects recovery outcomes that are not supported by the source-scoped resolution endpoint", () => {
|
||||
expect(
|
||||
resolveIssueRecoveryActionSchema.safeParse({
|
||||
outcome: "delegated",
|
||||
}).success,
|
||||
).toBe(false);
|
||||
|
||||
expect(
|
||||
resolveIssueRecoveryActionSchema.safeParse({
|
||||
outcome: "escalated",
|
||||
}).success,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("normalizes escaped line breaks in issue comment bodies", () => {
|
||||
const parsed = addIssueCommentSchema.parse({
|
||||
body: "Progress update\\r\\n\\r\\nNext action.",
|
||||
@@ -153,6 +219,50 @@ describe("issue validators", () => {
|
||||
}).workMode).toBe("planning");
|
||||
});
|
||||
|
||||
it("validates blocked inbox attention payloads and requires redacted secret fields", () => {
|
||||
const parsed = issueBlockedInboxAttentionSchema.parse({
|
||||
kind: "blocked",
|
||||
state: "needs_attention",
|
||||
reason: "blocked_by_unassigned_issue",
|
||||
severity: "critical",
|
||||
stoppedSinceAt: "2026-05-09T12:00:00.000Z",
|
||||
owner: { type: "unknown", agentId: null, userId: null, label: null },
|
||||
action: { label: "Assign blocker", detail: "Assign the leaf blocker." },
|
||||
sourceIssue: {
|
||||
id: "11111111-1111-4111-8111-111111111111",
|
||||
identifier: "PAP-1",
|
||||
title: "Blocked source",
|
||||
status: "blocked",
|
||||
priority: "high",
|
||||
assigneeAgentId: null,
|
||||
assigneeUserId: null,
|
||||
},
|
||||
leafIssue: {
|
||||
id: "22222222-2222-4222-8222-222222222222",
|
||||
identifier: "PAP-2",
|
||||
title: "Unassigned leaf",
|
||||
status: "todo",
|
||||
priority: "medium",
|
||||
assigneeAgentId: null,
|
||||
assigneeUserId: null,
|
||||
},
|
||||
recoveryIssue: null,
|
||||
approvalId: null,
|
||||
interactionId: null,
|
||||
sampleIssueIdentifier: "PAP-2",
|
||||
redaction: {
|
||||
externalDetailsRedacted: false,
|
||||
secretFieldsOmitted: true,
|
||||
},
|
||||
});
|
||||
|
||||
expect(parsed.redaction.secretFieldsOmitted).toBe(true);
|
||||
expect(issueBlockedInboxAttentionSchema.safeParse({
|
||||
...parsed,
|
||||
redaction: { externalDetailsRedacted: false, secretFieldsOmitted: false },
|
||||
}).success).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects unknown issue work modes", () => {
|
||||
expect(createIssueSchema.safeParse({ title: "Plan first", workMode: "normal" }).success).toBe(false);
|
||||
expect(suggestedTaskDraftSchema.safeParse({
|
||||
|
||||
@@ -14,6 +14,10 @@ import {
|
||||
ISSUE_COMMENT_PRESENTATION_TONES,
|
||||
ISSUE_MONITOR_SCHEDULED_BY,
|
||||
ISSUE_PRIORITIES,
|
||||
ISSUE_RECOVERY_ACTION_KINDS,
|
||||
ISSUE_RECOVERY_ACTION_OUTCOMES,
|
||||
ISSUE_RECOVERY_ACTION_OWNER_TYPES,
|
||||
ISSUE_RECOVERY_ACTION_STATUSES,
|
||||
ISSUE_WORK_MODES,
|
||||
clampIssueRequestDepth,
|
||||
ISSUE_STATUSES,
|
||||
@@ -24,6 +28,69 @@ import {
|
||||
} from "../constants.js";
|
||||
import { multilineTextSchema } from "./text.js";
|
||||
|
||||
export const issueBlockedInboxStateSchema = z.enum([
|
||||
"needs_attention",
|
||||
"awaiting_decision",
|
||||
"external_wait",
|
||||
"recovery_open",
|
||||
"missing_disposition",
|
||||
]);
|
||||
|
||||
export const issueBlockedInboxSeveritySchema = z.enum(["critical", "high", "medium", "low"]);
|
||||
|
||||
export const issueBlockedInboxReasonSchema = z.enum([
|
||||
"blocked_by_unassigned_issue",
|
||||
"blocked_by_assigned_backlog_issue",
|
||||
"blocked_by_uninvokable_assignee",
|
||||
"blocked_by_cancelled_issue",
|
||||
"blocked_chain_stalled",
|
||||
"invalid_review_participant",
|
||||
"in_review_without_action_path",
|
||||
"missing_successful_run_disposition",
|
||||
"pending_board_decision",
|
||||
"pending_user_decision",
|
||||
"external_owner_action",
|
||||
"open_recovery_issue",
|
||||
]);
|
||||
|
||||
export const issueBlockedInboxIssueRefSchema = z.object({
|
||||
id: z.string().uuid(),
|
||||
identifier: z.string().nullable(),
|
||||
title: z.string(),
|
||||
status: z.enum(ISSUE_STATUSES),
|
||||
priority: z.enum(ISSUE_PRIORITIES),
|
||||
assigneeAgentId: z.string().uuid().nullable(),
|
||||
assigneeUserId: z.string().nullable(),
|
||||
}).strict();
|
||||
|
||||
export const issueBlockedInboxAttentionSchema = z.object({
|
||||
kind: z.literal("blocked"),
|
||||
state: issueBlockedInboxStateSchema,
|
||||
reason: issueBlockedInboxReasonSchema,
|
||||
severity: issueBlockedInboxSeveritySchema,
|
||||
stoppedSinceAt: z.string().datetime().nullable(),
|
||||
owner: z.object({
|
||||
type: z.enum(["agent", "user", "board", "external", "unknown"]),
|
||||
agentId: z.string().uuid().nullable(),
|
||||
userId: z.string().nullable(),
|
||||
label: z.string().nullable(),
|
||||
}).strict(),
|
||||
action: z.object({
|
||||
label: z.string().trim().min(1),
|
||||
detail: z.string().nullable(),
|
||||
}).strict(),
|
||||
sourceIssue: issueBlockedInboxIssueRefSchema.nullable(),
|
||||
leafIssue: issueBlockedInboxIssueRefSchema.nullable(),
|
||||
recoveryIssue: issueBlockedInboxIssueRefSchema.nullable(),
|
||||
approvalId: z.string().uuid().nullable(),
|
||||
interactionId: z.string().uuid().nullable(),
|
||||
sampleIssueIdentifier: z.string().nullable(),
|
||||
redaction: z.object({
|
||||
externalDetailsRedacted: z.boolean(),
|
||||
secretFieldsOmitted: z.literal(true),
|
||||
}).strict(),
|
||||
}).strict();
|
||||
|
||||
export const ISSUE_EXECUTION_WORKSPACE_PREFERENCES = [
|
||||
"inherit",
|
||||
"shared_workspace",
|
||||
@@ -167,6 +234,89 @@ export const issueExecutionStateSchema = z.object({
|
||||
monitor: issueExecutionMonitorStateSchema.optional().nullable(),
|
||||
});
|
||||
|
||||
export const issueRecoveryActionReadModelSchema = z.object({
|
||||
id: z.string().uuid(),
|
||||
companyId: z.string().uuid(),
|
||||
sourceIssueId: z.string().uuid(),
|
||||
recoveryIssueId: z.string().uuid().nullable(),
|
||||
kind: z.enum(ISSUE_RECOVERY_ACTION_KINDS),
|
||||
status: z.enum(ISSUE_RECOVERY_ACTION_STATUSES),
|
||||
ownerType: z.enum(ISSUE_RECOVERY_ACTION_OWNER_TYPES),
|
||||
ownerAgentId: z.string().uuid().nullable(),
|
||||
ownerUserId: z.string().nullable(),
|
||||
previousOwnerAgentId: z.string().uuid().nullable(),
|
||||
returnOwnerAgentId: z.string().uuid().nullable(),
|
||||
cause: z.string().min(1),
|
||||
fingerprint: z.string().min(1),
|
||||
evidence: z.record(z.unknown()),
|
||||
nextAction: z.string().min(1),
|
||||
wakePolicy: z.record(z.unknown()).nullable(),
|
||||
monitorPolicy: z.record(z.unknown()).nullable(),
|
||||
attemptCount: z.number().int().nonnegative(),
|
||||
maxAttempts: z.number().int().positive().nullable(),
|
||||
timeoutAt: z.union([z.date(), z.string().datetime()]).nullable(),
|
||||
lastAttemptAt: z.union([z.date(), z.string().datetime()]).nullable(),
|
||||
outcome: z.enum(ISSUE_RECOVERY_ACTION_OUTCOMES).nullable(),
|
||||
resolutionNote: z.string().nullable(),
|
||||
resolvedAt: z.union([z.date(), z.string().datetime()]).nullable(),
|
||||
createdAt: z.union([z.date(), z.string().datetime()]),
|
||||
updatedAt: z.union([z.date(), z.string().datetime()]),
|
||||
});
|
||||
|
||||
export type IssueRecoveryActionReadModel = z.infer<typeof issueRecoveryActionReadModelSchema>;
|
||||
|
||||
const RESOLVE_ISSUE_RECOVERY_ACTION_OUTCOMES = [
|
||||
"restored",
|
||||
"false_positive",
|
||||
"blocked",
|
||||
"cancelled",
|
||||
] as const;
|
||||
|
||||
export const resolveIssueRecoveryActionSchema = z.object({
|
||||
actionId: z.string().uuid().optional(),
|
||||
outcome: z.enum(RESOLVE_ISSUE_RECOVERY_ACTION_OUTCOMES),
|
||||
sourceIssueStatus: z.enum(["done", "in_review", "blocked"]),
|
||||
resolutionNote: multilineTextSchema.optional().nullable(),
|
||||
}).strict().superRefine((value, ctx) => {
|
||||
if (value.outcome === "restored") {
|
||||
if (value.sourceIssueStatus !== "done" && value.sourceIssueStatus !== "in_review") {
|
||||
ctx.addIssue({
|
||||
code: z.ZodIssueCode.custom,
|
||||
message: "Restored recovery actions must move the source issue to done or in_review",
|
||||
path: ["sourceIssueStatus"],
|
||||
});
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
if (value.outcome === "blocked") {
|
||||
if (value.sourceIssueStatus !== "blocked") {
|
||||
ctx.addIssue({
|
||||
code: z.ZodIssueCode.custom,
|
||||
message: "Blocked recovery actions must move the source issue to blocked",
|
||||
path: ["sourceIssueStatus"],
|
||||
});
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
if (value.outcome === "false_positive" || value.outcome === "cancelled") {
|
||||
if (
|
||||
value.sourceIssueStatus !== "done" &&
|
||||
value.sourceIssueStatus !== "in_review"
|
||||
) {
|
||||
ctx.addIssue({
|
||||
code: z.ZodIssueCode.custom,
|
||||
message: "This recovery outcome requires sourceIssueStatus to be done or in_review",
|
||||
path: ["sourceIssueStatus"],
|
||||
});
|
||||
}
|
||||
return;
|
||||
}
|
||||
});
|
||||
|
||||
export type ResolveIssueRecoveryAction = z.infer<typeof resolveIssueRecoveryActionSchema>;
|
||||
|
||||
const issueRequestDepthInputSchema = z
|
||||
.number()
|
||||
.int()
|
||||
|
||||
Reference in New Issue
Block a user