create-academic-research 0.1.0

package/dist/src/project.js

@@ -0,0 +1,229 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+import { DEFAULT_AGENT, initializeCapabilities, installSkills } from "./capabilities.js";
+import { copyDirectory, exists, isNonEmptyDirectory, movePath, readJson, writeJson } from "./files.js";
+import { packageify, slugify, titleFromSlug } from "./names.js";
+import { AGENT_STACK } from "./stack.js";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const templateRoot = join(packageRoot, "template");
+const REQUIRED_CSV_COLUMNS = {
+    "sources/source-ledger.csv": [
+        "source_id",
+        "type",
+        "title",
+        "authors",
+        "year",
+        "venue",
+        "identifiers",
+        "raw_path",
+        "derived_path",
+        "bib_path",
+        "status",
+        "relevance",
+        "evidence_level",
+        "quality_notes",
+        "added_on",
+        "last_checked"
+    ],
+    "sources/conversion-ledger.csv": [
+        "source_id",
+        "input_path",
+        "output_path",
+        "tool",
+        "command_or_config",
+        "conversion_date",
+        "quality",
+        "checked_pages",
+        "known_issues"
+    ],
+    "sources/bib/citation-audit.csv": [
+        "citation_key",
+        "status",
+        "issue",
+        "source_id",
+        "claim_or_location",
+        "expected_fix",
+        "checked_on"
+    ],
+    "sota/literature-matrix.csv": [
+        "source_id",
+        "title",
+        "authors",
+        "year",
+        "venue",
+        "method",
+        "dataset_or_sample",
+        "task_or_problem",
+        "key_claim",
+        "metric_or_result",
+        "limitations",
+        "relevance",
+        "citation_count_or_signal",
+        "identifiers"
+    ],
+    "sota/screening-decisions.csv": ["stage", "source_id", "title", "decision", "reason", "screened_by", "date"],
+    "experiments/registry.csv": [
+        "run_id",
+        "date",
+        "git_commit",
+        "question",
+        "hypothesis",
+        "command",
+        "config",
+        "seed",
+        "dataset",
+        "metric",
+        "result",
+        "runtime",
+        "status",
+        "record_path"
+    ]
+};
+export async function createProject(options) {
+    const target = resolve(options.target);
+    if (await isNonEmptyDirectory(target)) {
+        throw new Error(`target directory is not empty: ${target}`);
+    }
+    const title = options.title ?? titleFromSlug(options.slug ?? basename(target));
+    const slug = slugify(options.slug ?? title);
+    const packageName = packageify(options.packageName ?? slug);
+    const preset = options.preset ?? "default";
+    const agent = options.agent ?? DEFAULT_AGENT;
+    if (!AGENT_STACK.presets[preset]) {
+        throw new Error(`unknown capability preset: ${preset}`);
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await copyDirectory(templateRoot, target);
+    await personalizeProject(target, { title, slug, packageName, profile: options.profile ?? "academic-general" });
+    await writeGeneratedPackageJson(target, { slug });
+    await writeAgentStack(target);
+    await initializeCapabilities(target, { preset, agent });
+    if (options.installSkills) {
+        await installSkills(target, preset);
+    }
+    return { root: target, title, slug, packageName };
+}
+export async function renameProject(root, options) {
+    const target = resolve(root);
+    const configPath = join(target, "configs/default.yaml");
+    const config = YAML.parse(await readFile(configPath, "utf8"));
+    const previousPackage = config.project.package;
+    const title = options.title ?? config.project.title;
+    const slug = options.slug === undefined ? config.project.slug : slugify(options.slug);
+    const packageName = options.packageName === undefined ? config.project.package : packageify(options.packageName);
+    await personalizeProject(target, {
+        title,
+        slug,
+        packageName,
+        profile: config.project.profile,
+        previousPackage
+    });
+    await writeGeneratedPackageJson(target, { slug });
+    return { root: target, title, slug, packageName };
+}
+export async function doctorProject(root) {
+    const target = resolve(root);
+    const errors = [];
+    const required = [
+        "README.md",
+        "package.json",
+        "pyproject.toml",
+        "AGENTS.md",
+        "configs/default.yaml",
+        "configs/agent-stack.yaml",
+        "configs/capabilities.yaml",
+        "docs/agent/capability-profile.md",
+        "docs/agent/generated",
+        "sources/source-ledger.csv",
+        "sota/literature-matrix.csv",
+        "wiki/index.md",
+        "wiki/log.md"
+    ];
+    for (const relative of required) {
+        if (!(await exists(join(target, relative))))
+            errors.push(`missing ${relative}`);
+    }
+    if (await exists(join(target, "configs/default.yaml"))) {
+        try {
+            const config = YAML.parse(await readFile(join(target, "configs/default.yaml"), "utf8"));
+            if (!config?.project?.package) {
+                errors.push("configs/default.yaml missing project.package");
+            }
+            else if (!(await exists(join(target, "src", config.project.package, "__init__.py")))) {
+                errors.push(`missing src/${config.project.package}/__init__.py`);
+            }
+        }
+        catch (error) {
+            errors.push(`invalid configs/default.yaml: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (await exists(join(target, "configs/capabilities.yaml"))) {
+        try {
+            YAML.parse(await readFile(join(target, "configs/capabilities.yaml"), "utf8"));
+        }
+        catch (error) {
+            errors.push(`invalid configs/capabilities.yaml: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    for (const [relative, requiredColumns] of Object.entries(REQUIRED_CSV_COLUMNS)) {
+        await validateCsvHeader(target, relative, requiredColumns, errors);
+    }
+    return { ok: errors.length === 0, errors };
+}
+async function personalizeProject(root, { title, slug, packageName, profile, previousPackage = "project_package" }) {
+    const configPath = join(root, "configs/default.yaml");
+    const config = YAML.parse(await readFile(configPath, "utf8"));
+    config.project = {
+        ...config.project,
+        slug,
+        title,
+        profile,
+        package: packageName
+    };
+    await writeFile(configPath, YAML.stringify(config), "utf8");
+    const pyprojectPath = join(root, "pyproject.toml");
+    const pyproject = await readFile(pyprojectPath, "utf8");
+    await writeFile(pyprojectPath, pyproject.replace(/^name = ".*"$/m, `name = "${slug}"`), "utf8");
+    const readmePath = join(root, "README.md");
+    const readme = await readFile(readmePath, "utf8");
+    await writeFile(readmePath, readme.replace(/^# .*/m, `# ${title}`), "utf8");
+    const previous = join(root, "src", previousPackage);
+    const next = join(root, "src", packageName);
+    if (previous !== next && (await exists(previous))) {
+        await movePath(previous, next);
+    }
+    else {
+        await mkdir(dirname(join(next, "__init__.py")), { recursive: true });
+        if (!(await exists(join(next, "__init__.py")))) {
+            await writeFile(join(next, "__init__.py"), "\"\"\"Project package.\"\"\"\n", "utf8");
+        }
+    }
+}
+async function writeGeneratedPackageJson(root, { slug }) {
+    const path = join(root, "package.json");
+    const data = await readJson(path);
+    const existingSpec = data.devDependencies?.["create-academic-research"];
+    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ?? existingSpec ?? "^0.1.0";
+    data.name = slug;
+    data.devDependencies = {
+        ...(data.devDependencies ?? {}),
+        "create-academic-research": packageSpec
+    };
+    await writeJson(path, data);
+}
+async function writeAgentStack(root) {
+    await writeFile(join(root, "configs/agent-stack.yaml"), YAML.stringify(AGENT_STACK), "utf8");
+}
+async function validateCsvHeader(root, relative, requiredColumns, errors) {
+    const path = join(root, relative);
+    if (!(await exists(path)))
+        return;
+    const header = (await readFile(path, "utf8")).split(/\r?\n/, 1)[0] ?? "";
+    const columns = new Set(header.split(",").map((column) => column.trim()).filter(Boolean));
+    for (const column of requiredColumns) {
+        if (!columns.has(column))
+            errors.push(`${relative} missing column ${column}`);
+    }
+}

package/dist/src/prompts.d.ts

@@ -0,0 +1,18 @@
+export interface CreatePromptDefaults {
+    title: string;
+    slug: string;
+    packageName: string;
+    preset: string;
+    agent: string;
+    installSkills: boolean;
+    installMcpTools: boolean;
+}
+export interface CreatePromptAnswers extends CreatePromptDefaults {
+    installSkills: boolean;
+    installMcpTools: boolean;
+}
+export interface CreatePromptLocks {
+    installSkills?: boolean;
+    installMcpTools?: boolean;
+}
+export declare function askCreateOptions(defaults: CreatePromptDefaults, locks?: CreatePromptLocks): Promise<CreatePromptAnswers>;

package/dist/src/prompts.js

@@ -0,0 +1,29 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+export async function askCreateOptions(defaults, locks = {}) {
+    const rl = createInterface({ input, output });
+    try {
+        const title = await question(rl, "Project title", defaults.title);
+        const slug = await question(rl, "Project slug", defaults.slug);
+        const packageName = await question(rl, "Python package", defaults.packageName);
+        const preset = await question(rl, "Capability preset", defaults.preset);
+        const agent = await question(rl, "Agent target", defaults.agent);
+        const installSkills = locks.installSkills ?? (await yesNo(rl, "Install project-local skills now", defaults.installSkills));
+        const installMcpTools = locks.installMcpTools ?? (await yesNo(rl, "Run external MCP installers now", defaults.installMcpTools));
+        return { title, slug, packageName, preset, agent, installSkills, installMcpTools };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function question(rl, prompt, fallback) {
+    const answer = await rl.question(`${prompt} [${fallback}]: `);
+    return answer.trim() || fallback;
+}
+async function yesNo(rl, prompt, fallback) {
+    const label = fallback ? "Y/n" : "y/N";
+    const answer = (await rl.question(`${prompt} [${label}]: `)).trim().toLowerCase();
+    if (!answer)
+        return fallback;
+    return ["y", "yes", "s", "si"].includes(answer);
+}

package/dist/src/runner.d.ts

@@ -0,0 +1,12 @@
+import { type StdioOptions } from "node:child_process";
+export interface RunnerOptions {
+    cwd?: string;
+    stdio?: StdioOptions;
+}
+export interface CommandResult {
+    code: number;
+}
+export interface Runner {
+    run(command: string[], options?: RunnerOptions): Promise<CommandResult>;
+}
+export declare const defaultRunner: Runner;

package/dist/src/runner.js

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+export const defaultRunner = {
+    run(command, options = {}) {
+        const executable = command[0];
+        if (!executable)
+            throw new Error("cannot run an empty command");
+        return new Promise((resolve, reject) => {
+            const child = spawn(executable, command.slice(1), {
+                cwd: options.cwd,
+                stdio: options.stdio ?? "inherit",
+                shell: false
+            });
+            child.on("error", reject);
+            child.on("exit", (code) => {
+                if (code === 0)
+                    resolve({ code });
+                else
+                    reject(new Error(`command failed (${code}): ${command.join(" ")}`));
+            });
+        });
+    }
+};

package/dist/src/stack.d.ts

@@ -0,0 +1,30 @@
+export interface SkillBundle {
+    description: string;
+    commands: string[];
+}
+export interface CapabilityPreset {
+    description: string;
+    skill_bundles: string[];
+    mcp_servers: string[];
+}
+export interface McpServer {
+    priority: string;
+    source_need: string;
+    install_command: string;
+    uninstall_command: string;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    smoke_test: string;
+    risks: string;
+}
+export interface AgentStack {
+    version: number;
+    description: string;
+    skill_bundles: Record<string, SkillBundle>;
+    presets: Record<string, CapabilityPreset>;
+    mcp_servers: Record<string, McpServer>;
+}
+export type McpToolCommandKey = "install_command" | "uninstall_command";
+export declare const AGENT_STACK: AgentStack;
+export declare function presetMcpServers(preset: string): string[];

package/dist/src/stack.js

@@ -0,0 +1,180 @@
+export const AGENT_STACK = {
+    version: 1,
+    description: "Project-local academic research capability stack.",
+    skill_bundles: {
+        academic_research: {
+            description: "Research-native workflow skills.",
+            commands: [
+                "npm exec --yes --package skills -- skills add VincenzoImp/academic-research-skills {agent_flag} --skill '*' --copy -y"
+            ]
+        },
+        default_complementary: {
+            description: "General agent engineering, document, frontend, testing, and skill helpers.",
+            commands: [
+                "npm exec --yes --package skills -- skills add obra/superpowers {agent_flag} --skill '*' --copy -y",
+                "npm exec --yes --package skills -- skills add anthropics/skills {agent_flag} --skill frontend-design webapp-testing skill-creator mcp-builder pdf docx xlsx pptx --copy -y"
+            ]
+        },
+        docling: {
+            description: "PDF and document conversion helper.",
+            commands: [
+                "npm exec --yes --package skills -- skills add existential-birds/beagle {agent_flag} --skill docling --copy -y"
+            ]
+        },
+        optional_connectors: {
+            description: "CLI-side literature connectors to use only when MCP servers are unavailable.",
+            commands: [
+                "npm exec --yes --package skills -- skills add davila7/claude-code-templates {agent_flag} --skill openalex-database --copy -y",
+                "npm exec --yes --package skills -- skills add agents365-ai/365-skills {agent_flag} --skill semanticscholar-skill --copy -y",
+                "npm exec --yes --package skills -- skills add fuzhiyu/researchprojecttemplate {agent_flag} --skill zotero-paper-reader --copy -y"
+            ]
+        },
+        optional_mechanical_specialists: {
+            description: "Narrow mechanical helpers that do not replace project-native governance.",
+            commands: [
+                "npm exec --yes --package skills -- skills add bahayonghang/academic-writing-skills {agent_flag} --skill latex-paper-en --copy -y",
+                [
+                    "npm exec --yes --package skills -- skills add lllllllama/ai-paper-reproduction-skill",
+                    "{agent_flag}",
+                    "--skill",
+                    [
+                        "ai-research-reproduction",
+                        "repo-intake-and-plan",
+                        "env-and-assets-bootstrap",
+                        "minimal-run-and-audit",
+                        "paper-context-resolver",
+                        "analyze-project",
+                        "safe-debug",
+                        "run-train",
+                        "explore-run",
+                        "explore-code"
+                    ].join(" "),
+                    "--copy -y"
+                ].join(" ")
+            ]
+        }
+    },
+    presets: {
+        minimal: {
+            description: "Only the academic research skill package.",
+            skill_bundles: ["academic_research"],
+            mcp_servers: []
+        },
+        default: {
+            description: "Recommended setup for most academic research projects.",
+            skill_bundles: ["academic_research", "default_complementary", "docling"],
+            mcp_servers: ["arxiv", "semantic-scholar", "openalex"]
+        },
+        literature: {
+            description: "Literature-heavy SOTA, survey, scoping, or systematic review setup.",
+            skill_bundles: ["academic_research", "default_complementary", "docling"],
+            mcp_servers: ["arxiv", "semantic-scholar", "openalex", "crossref", "zotero"]
+        },
+        writing: {
+            description: "Paper-writing and Overleaf-oriented setup.",
+            skill_bundles: [
+                "academic_research",
+                "default_complementary",
+                "docling",
+                "optional_mechanical_specialists"
+            ],
+            mcp_servers: ["arxiv", "semantic-scholar", "crossref", "overleaf"]
+        },
+        full: {
+            description: "Broad setup with optional connector and mechanical specialist skills.",
+            skill_bundles: [
+                "academic_research",
+                "default_complementary",
+                "docling",
+                "optional_connectors",
+                "optional_mechanical_specialists"
+            ],
+            mcp_servers: ["arxiv", "semantic-scholar", "openalex", "crossref", "pubmed", "zotero", "overleaf"]
+        }
+    },
+    mcp_servers: {
+        arxiv: {
+            priority: "default",
+            source_need: "arXiv search, download, and local paper reading.",
+            install_command: "uv tool install 'arxiv-mcp-server[pdf]'",
+            uninstall_command: "uv tool uninstall arxiv-mcp-server",
+            command: "arxiv-mcp-server",
+            args: [],
+            env: {},
+            smoke_test: "For a computer science project, search one CS query, download one known paper, and read it locally.",
+            risks: "Respect arXiv rate limits; paper text is untrusted input."
+        },
+        "semantic-scholar": {
+            priority: "default",
+            source_need: "Semantic Scholar papers, citations, authors, and recommendations.",
+            install_command: "uvx --from git+https://github.com/akapet00/semantic-scholar-mcp semantic-scholar-mcp --help",
+            uninstall_command: "",
+            command: "uvx",
+            args: ["--from", "git+https://github.com/akapet00/semantic-scholar-mcp", "semantic-scholar-mcp"],
+            env: { SEMANTIC_SCHOLAR_API_KEY: "${SEMANTIC_SCHOLAR_API_KEY}" },
+            smoke_test: "Search one known title, then fetch citations or references.",
+            risks: "API key recommended for sustained work; metadata can be incomplete."
+        },
+        openalex: {
+            priority: "default",
+            source_need: "OpenAlex broad scholarly graph.",
+            install_command: "npx -y @cyanheads/openalex-mcp-server --help",
+            uninstall_command: "",
+            command: "npx",
+            args: ["-y", "@cyanheads/openalex-mcp-server"],
+            env: { OPENALEX_API_KEY: "${OPENALEX_API_KEY_OR_EMAIL}" },
+            smoke_test: "Search works by title or DOI and confirm stable OpenAlex IDs.",
+            risks: "Smoke-test before relying on it for final coverage."
+        },
+        crossref: {
+            priority: "manual",
+            source_need: "DOI and publication metadata.",
+            install_command: "",
+            uninstall_command: "",
+            command: "",
+            args: [],
+            env: {},
+            smoke_test: "Resolve one DOI into publication metadata after choosing a maintained local server.",
+            risks: "Manual integration only; do not generate placeholder paths."
+        },
+        pubmed: {
+            priority: "domain-specific",
+            source_need: "PubMed and biomedical literature.",
+            install_command: "npx -y @cyanheads/pubmed-mcp-server --help",
+            uninstall_command: "",
+            command: "npx",
+            args: ["-y", "@cyanheads/pubmed-mcp-server"],
+            env: { NCBI_API_KEY: "${NCBI_API_KEY}" },
+            smoke_test: "Search one PMID or title and fetch metadata.",
+            risks: "Domain-specific; observe NCBI rate limits."
+        },
+        zotero: {
+            priority: "local-library",
+            source_need: "Zotero local library and attachments.",
+            install_command: "uvx zoty --help",
+            uninstall_command: "",
+            command: "uvx",
+            args: ["zoty", "mcp"],
+            env: {},
+            smoke_test: "List collections, search one known item, and export BibTeX.",
+            risks: "Requires Zotero local API and bridge setup."
+        },
+        overleaf: {
+            priority: "writing",
+            source_need: "Overleaf project sync.",
+            install_command: "uv tool install overleaf-mcp-server",
+            uninstall_command: "uv tool uninstall overleaf-mcp-server",
+            command: "overleaf-mcp",
+            args: ["serve"],
+            env: { OVERLEAF_TOKEN: "${OVERLEAF_TOKEN}" },
+            smoke_test: "List projects or read one .tex file; do not write by default.",
+            risks: "Requires token setup; write access needs explicit approval."
+        }
+    }
+};
+export function presetMcpServers(preset) {
+    const config = AGENT_STACK.presets[preset];
+    if (!config)
+        throw new Error(`unknown capability preset: ${preset}`);
+    return [...config.mcp_servers];
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "create-academic-research",
+  "version": "0.1.0",
+  "description": "Create and manage agent-ready academic research repositories.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Vincenzo Imperati",
+  "keywords": [
+    "academic-research",
+    "research-project",
+    "agent-skills",
+    "mcp",
+    "literature-review",
+    "reproducibility"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VincenzoImp/create-academic-research.git"
+  },
+  "bugs": {
+    "url": "https://github.com/VincenzoImp/create-academic-research/issues"
+  },
+  "homepage": "https://github.com/VincenzoImp/create-academic-research#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "create-academic-research": "dist/bin/create-academic-research.js",
+    "academic-research": "dist/bin/academic-research.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test",
+    "lint": "npm run typecheck && node scripts/validate.mjs",
+    "release:check": "node scripts/check-release.mjs",
+    "prepare": "npm run build",
+    "audit:local": "npm test && npm run lint"
+  },
+  "dependencies": {
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "typescript": "^5.9.3"
+  }
+}

package/template/AGENTS.md

@@ -0,0 +1,47 @@
+# Agent Operating Guide
+
+This is an academic research project. Treat it as both a software project and a
+scholarly record.
+
+## Core Rules
+
+- Preserve source originals under `sources/`, `data/raw/`, and `data/external/`.
+- Keep reusable logic in `src/`; keep notebooks for exploration and narrative output.
+- Tie claims to sources, datasets, experiment records, or decision records.
+- Update durable records when project knowledge changes.
+- Keep large data, generated caches, credentials, and private review material out of git.
+
+## First Read
+
+1. `README.md`
+2. `configs/default.yaml`
+3. `configs/capabilities.yaml`
+4. `docs/agent/capability-profile.md`
+5. `docs/agent/research-program.md`
+6. `wiki/index.md`
+
+## Standard Workflow
+
+1. Identify whether the task affects sources, data, methods, experiments, claims, writing, or agent setup.
+2. Use project-local skills when available; route ambiguous work through `research-project-router`.
+3. Make repeatable changes in `src/`, `configs/`, or documented workflows.
+4. Add tests or validation for code and structural changes.
+5. Update `wiki/log.md` and affected wiki/docs pages before finishing.
+
+## Memory Contract
+
+- `wiki/log.md` is chronological and append-only.
+- `wiki/index.md` indexes reusable pages.
+- `wiki/synthesis.md` changes only when the project-level interpretation changes.
+- `wiki/open_questions.md` tracks unresolved questions.
+- `wiki/contradictions.md` tracks conflicts across sources, data, or runs.
+
+## Evidence
+
+- Native PDFs and reports go in `sources/pdfs/`.
+- Derived Markdown goes in `sources/markdown/`.
+- Metadata goes in `sources/metadata/`.
+- Bibliography records go in `sources/bib/references.bib`.
+- Citation issues go in `sources/bib/citation-audit.csv`.
+- SOTA records go in `sota/`.
+- Curated experiment records go in `experiments/`.