mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:48:15 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `AGENTS.md` tells every contributor and agent to read `doc/DEVELOPING.md` for setup, commands, testing, and worktrees > - That file grew to 5,495 lines. Most of it was notes on how one subsystem behaves, added one pull request at a time > - Readers could not find the commands. Agents also read behavior notes as rules > - This pull request cuts `doc/DEVELOPING.md` to a 660-line setup and workflow guide. It moves the subsystem notes to focused docs > - The benefit is a guide that a person or an agent can read in full, and a clear place for each kind of note ## Linked Issues or Issue Description **Issue type** Outdated or confusing documentation. **Where is the issue?** `doc/DEVELOPING.md` **What's wrong?** The file was 5,495 lines. It opened with 112 lines about case handoffs before it reached Prerequisites. Unrelated sections sat below the "OpenClaw Docker UI One-Command Script" heading. Statements about current behavior read like policy. **Suggested fix** Keep setup, commands, and workflow in `doc/DEVELOPING.md`. Move each subsystem note to a doc for that subsystem. Add an index. ## What Changed - `doc/DEVELOPING.md` is now 660 lines: prerequisites, start dev, health checks, local run, test drive, Docker, instance layout, database, storage, secrets, worktrees, test commands, Storybook, CLI, and an index of the other docs. - 15 new docs hold the moved text without wording changes: `ci-workflows`, `test-infrastructure`, `worktrees`, `hot-restart-deploys`, `heartbeat-internals`, `runner-internals`, `workspace-repositories`, `workspace-storage`, `skills-and-teams-catalog`, `ui-internals`, `case-handoffs`, `chat-connector-development`, `instance-configuration`, `integration-api-notes`, `database-backups`. - "Publish a branch Storybook" moved to `doc/STORYBOOK-DEPLOYMENT.md`. The privacy rollout notes moved to `doc/ISSUE-PRIVACY.md`. - Deleted about 280 lines: the story-by-story Storybook notes, "Agent Artifact Uploads" (a copy of `doc/AGENT-ARTIFACTS.md`), two pointer-only sections, "Workspace feature checks (2026-10-09)", and "Chat and task navigation caching". The test-drive build-lock paragraph is now four lines. - Repointed every inbound link and every script or workflow comment that named a moved section. - `AGENTS.md` now says where a behavior note goes, so the guide does not grow again. ## Verification - A script split the file by line range. It asserts that each of the 5,495 source lines is kept, moved, or dropped exactly one time. - A link check on every changed Markdown file found 0 missing files and 0 missing anchors. - `node scripts/check-maps.mjs` passes. - `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail. - `node --check` passes on the three scripts with changed comments. - `pnpm verify` was not run. This worktree has no installed dependencies, and the change has no runtime code. ## Risks - Low risk. The change is documentation and comments only. - A link to a moved section from outside this repository will land on the top of `doc/DEVELOPING.md`. - The new docs are not in the audited prose list in `.github/scripts/ci-inputs.mjs`. An edit to one of them runs full CI. An edit to `doc/DEVELOPING.md` does not. This PR does not change that list. ## Model Used - Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, with tool use. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [ ] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
139 lines
5.1 KiB
JavaScript
139 lines
5.1 KiB
JavaScript
#!/usr/bin/env node
|
|
// Typechecks the test projects outside `pnpm -r`.
|
|
//
|
|
// Each project imports server source through relative paths, so its tsconfig.json
|
|
// is one program over most of the server. Its tsconfig.layers.json reads that
|
|
// source as the declarations from server/scripts/typecheck-layers.mjs, which this
|
|
// script builds first. It then fails if a project still loads server source,
|
|
// because that is what makes these programs large. See "Typecheck memory" in
|
|
// doc/test-infrastructure.md.
|
|
//
|
|
// --reuse-declarations skips the build. Use it only straight after a server
|
|
// typecheck on the same commit, because stale declarations pass silently.
|
|
//
|
|
// Usage: node scripts/typecheck-test-projects.mjs [--low-memory] [--reuse-declarations] [project ...]
|
|
|
|
import { spawnSync } from "node:child_process";
|
|
import path from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import { LOW_MEMORY_VARIABLE, runTsc } from "./run-tsc.mjs";
|
|
import { runPnpm } from "./typecheck-low-memory.mjs";
|
|
import { isTestFile, typecheckLayers } from "../server/scripts/typecheck-layers.mjs";
|
|
|
|
export const PROJECTS = [
|
|
"server/src/__tests__/helpers/maintenance",
|
|
"tests/e2e",
|
|
"tests/lifecycle-baseline",
|
|
"tests/restart-chaos",
|
|
"tests/runner-e2e",
|
|
"tests/speko-native",
|
|
];
|
|
|
|
// The same steps as the server's typecheck script.
|
|
export const PREPARE_STEPS = [
|
|
["--filter", "@paperclipai/paperclip-runner", "run", "build:typescript"],
|
|
["--filter", "@paperclipai/plugin-sdk", "ensure-build-deps"],
|
|
];
|
|
|
|
/**
|
|
* Finds the server source in a program's file list, as paths relative to the
|
|
* server. Test support files have no layer, and declaration and JSON files add
|
|
* little, so only other source files count.
|
|
*/
|
|
export function findServerSource(files, serverRoot) {
|
|
return files
|
|
.map((file) => path.relative(serverRoot, file).split(path.sep).join("/"))
|
|
.filter(
|
|
(file) =>
|
|
file.startsWith("src/") && /\.[cm]?[jt]sx?$/.test(file) && !/\.d\.[cm]?ts$/.test(file) && !isTestFile(file),
|
|
);
|
|
}
|
|
|
|
function listProgramFiles(config, { cwd, env }) {
|
|
const tsc = path.join(cwd, "node_modules", "typescript", "bin", "tsc");
|
|
const result = spawnSync(process.execPath, [tsc, "-p", config, "--listFilesOnly"], {
|
|
cwd,
|
|
env,
|
|
encoding: "utf8",
|
|
maxBuffer: 1 << 26,
|
|
});
|
|
if (result.error) throw result.error;
|
|
return { status: result.status ?? 1, files: result.stdout.split("\n").filter(Boolean), output: result.stdout };
|
|
}
|
|
|
|
export function typecheckTestProjects({
|
|
root,
|
|
projects = PROJECTS,
|
|
reuseDeclarations = false,
|
|
env = process.env,
|
|
pnpm = runPnpm,
|
|
run = runTsc,
|
|
listFiles = listProgramFiles,
|
|
log = console.log,
|
|
logError = console.error,
|
|
}) {
|
|
const serverRoot = path.join(root, "server");
|
|
if (!reuseDeclarations) {
|
|
for (const args of PREPARE_STEPS) {
|
|
const status = pnpm(args, { cwd: root, env });
|
|
if (status !== 0) return status;
|
|
}
|
|
|
|
const layers = typecheckLayers({
|
|
serverRoot,
|
|
declarationsOnly: true,
|
|
run: (args, options) => run(args, { ...options, env }),
|
|
log,
|
|
});
|
|
// Report the server's own errors first. They would repeat in each project.
|
|
if (layers !== 0) return layers;
|
|
}
|
|
|
|
let exitCode = 0;
|
|
for (const project of projects) {
|
|
log(`typecheck:test-projects: ${project}`);
|
|
const config = path.posix.join(project, "tsconfig.layers.json");
|
|
const { status, signal } = run(["-p", config], { cwd: root, env });
|
|
if (signal) return status || 1;
|
|
if (status !== 0) exitCode = status;
|
|
|
|
const listing = listFiles(config, { cwd: root, env });
|
|
if (listing.status !== 0) {
|
|
logError(`typecheck:test-projects: could not list the files of ${project}\n${listing.output ?? ""}`);
|
|
exitCode ||= listing.status;
|
|
continue;
|
|
}
|
|
const source = findServerSource(listing.files, serverRoot);
|
|
if (source.length > 0) {
|
|
logError(
|
|
`typecheck:test-projects: ${project} loads ${source.length} server source files. ` +
|
|
`It must read them as layer declarations. First files: ${source.slice(0, 5).join(", ")}`,
|
|
);
|
|
exitCode ||= 1;
|
|
}
|
|
}
|
|
return exitCode;
|
|
}
|
|
|
|
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
const args = process.argv.slice(2);
|
|
const flags = args.filter((arg) => arg.startsWith("--"));
|
|
const projects = args.filter((arg) => !arg.startsWith("--"));
|
|
const unknownFlags = flags.filter((flag) => !["--low-memory", "--reuse-declarations"].includes(flag));
|
|
const unknown = projects.filter((project) => !PROJECTS.includes(project));
|
|
if (unknownFlags.length > 0) {
|
|
console.error(`Unknown option: ${unknownFlags.join(", ")}`);
|
|
process.exitCode = 2;
|
|
} else if (unknown.length > 0) {
|
|
console.error(`Unknown project: ${unknown.join(", ")}. Known projects: ${PROJECTS.join(", ")}`);
|
|
process.exitCode = 2;
|
|
} else {
|
|
process.exitCode = typecheckTestProjects({
|
|
root: path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."),
|
|
projects: projects.length > 0 ? projects : PROJECTS,
|
|
reuseDeclarations: flags.includes("--reuse-declarations"),
|
|
env: args.includes("--low-memory") ? { ...process.env, [LOW_MEMORY_VARIABLE]: "1" } : process.env,
|
|
});
|
|
}
|
|
}
|