blank-agentic-cli 0.1.0__py3-none-any.whl

blank_agentic_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: blank-agentic-cli
+Version: 0.1.0
+Summary: CLI scaffolder for agentic AI research projects
+Author: Shusuke Ioku
+License: MIT
+Project-URL: Homepage, https://github.com/shusuke-ioku/blank
+Project-URL: Repository, https://github.com/shusuke-ioku/blank
+Project-URL: Issues, https://github.com/shusuke-ioku/blank/issues
+Keywords: cli,scaffold,research,agentic-ai,typst
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# blank
+
+`blank` is a CLI scaffolder for research projects driven by agentic AI workflows.
+
+## Install
+
+From PyPI (after release):
+
+```bash
+pipx install blank-agentic-cli
+```
+
+From GitHub:
+
+```bash
+pipx install git+https://github.com/shusuke-ioku/blank.git
+```
+
+## Usage
+
+```bash
+blank init
+blank init my-project
+blank init my-project --project-name "My Project"
+blank init my-project --dry-run
+blank init my-project --force
+blank init my-project --no-agents
+blank init my-project --paper-template latex
+blank init my-project --paper-template blank
+```
+
+If `--paper-template` is omitted and you run in a terminal, `blank init` asks you to choose:
+- `latex`: LaTeX-like Typst starter
+- `blank`: minimal empty Typst file
+
+## Generated scaffold
+
+- `analysis/scripts/`
+- `analysis/data/`
+- `analysis/output/`
+- `paper/`
+- `idea/`
+- `.codex/` and `.claude/` by default
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e . pytest
+pytest
+```
+
+## Release (PyPI)
+
+1. Create PyPI project `blank-agentic-cli` and enable Trusted Publishing for this GitHub repo.
+2. (Optional) Run GitHub Action `publish` manually with `testpypi` to verify packaging.
+3. Tag a release:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+4. The `publish` workflow builds and uploads to PyPI.

blank_agentic_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+blank_agentic_cli-0.1.0.dist-info/licenses/LICENSE,sha256=MRBn9GxVpiQ-55qAQkGpU7p7Ljy8XgpXlJVUZxf3urk,1069
+blank_cli/__init__.py,sha256=4t_crzhrLum--oyowUMxtjBTzUtWp7oRTF22ewEvJG4,49
+blank_cli/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+blank_cli/cli.py,sha256=XekEayeZmmgYoy3OxMyuoidJY1AbKJ9uCmO7aGzxMIw,3686
+blank_cli/scaffold.py,sha256=EWavwWZBSfREcBmG-Jru1SgtNcNfKU5spMYEn7-ONwo,6064
+blank_cli/templates/.gitignore.tpl,sha256=rX3wTwZbiukecTU11CdnpbP6uGER3bYxUMTyv8DwymM,220
+blank_cli/templates/.here.tpl,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+blank_cli/templates/README.md.tpl,sha256=nH_JARSx86LLxLTPvkKMiH3SM2jtyHUf9qwo53_NNGY,392
+blank_cli/templates/.claude/settings.local.json.tpl,sha256=7m0QNJhb4G3eYAXAb4iQUxOoayhkUuh1apd6bN9V_Ls,43
+blank_cli/templates/.codex/config.toml.tpl,sha256=1O8PWj3W7pyP07MWVOaTvHUVXcHmDK0Fs54GNJd5PKU,154
+blank_cli/templates/.codex/project.md.tpl,sha256=PiVPviq4OH1nrvG2LDB98kFVdKJep2KXYuhFq_JfUro,382
+blank_cli/templates/analysis/data/codebook.md.tpl,sha256=-Xk1AjYzRTXJ-4kL6WfLMuAmnokaQGoR33dVjSBM0uQ,214
+blank_cli/templates/analysis/output/figures/.gitkeep.tpl,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+blank_cli/templates/analysis/output/results/.gitkeep.tpl,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+blank_cli/templates/analysis/output/tables/.gitkeep.tpl,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+blank_cli/templates/analysis/scripts/00_setup.R.tpl,sha256=r0gCODXKfVTpsOl0IamUWx7MpgNqE5MW75LoOkBvx7I,174
+blank_cli/templates/analysis/scripts/20_data.R.tpl,sha256=-i_dgFWTCUmbIAuicdZhBjEt3ZQHhc_NoyYTZTka6yE,125
+blank_cli/templates/analysis/scripts/30_results_main.R.tpl,sha256=Soa_wWAnI47oL8XP8zbh1jvCVgrIDHwSExqGiM1gYeA,191
+blank_cli/templates/paper/aesthetics.typ.tpl,sha256=3GhiK02rsowbz72kJrjpJ9HwOV7n4iN15-Ss0qBRAlE,65
+blank_cli/templates/paper/paper_blank.typ.tpl,sha256=cOWcOc6yL-R0b1G1WgCb2bceQacr4cjIECMIfHq3FK0,19
+blank_cli/templates/paper/paper_latex.typ.tpl,sha256=4flbPQ3FhDISToXhohQ1i2i9acLa5Q7CXq0JOvnu1yk,300
+blank_cli/templates/paper/ref.bib.tpl,sha256=oNfPSWJdTpuwQkCIVuiP_O4RoMgQ3NZbLqICIeu5hyk,133
+blank_agentic_cli-0.1.0.dist-info/METADATA,sha256=2L_U7NeWP2xJ_YpTGDhHC1xXA-YNG__GsfWFMI3P8XU,2177
+blank_agentic_cli-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+blank_agentic_cli-0.1.0.dist-info/entry_points.txt,sha256=ivuRUixJGWOksbVr4a70y9W2HnY6wE9UHOejY8qHbWk,45
+blank_agentic_cli-0.1.0.dist-info/top_level.txt,sha256=AMjS8r2y0yWcJKEo_QWbS8G4df-6z54w884ny1gXA6M,10
+blank_agentic_cli-0.1.0.dist-info/RECORD,,

blank_agentic_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

blank_agentic_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+blank = blank_cli.cli:main

blank_agentic_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shusuke Ioku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blank_agentic_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+blank_cli

blank_cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

blank_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

blank_cli/cli.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib import resources
+from pathlib import Path
+
+from .scaffold import ScaffoldConflictError, apply_actions, plan_actions
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="blank", description="Scaffold research projects")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Initialize a research project scaffold")
+    init_parser.add_argument("target_dir", nargs="?", default=".", help="Target directory (default: current directory)")
+    init_parser.add_argument(
+        "--project-name",
+        help="Project name used in generated template files (default: target directory name)",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite scaffold files when they already exist and differ",
+    )
+    init_parser.add_argument("--dry-run", action="store_true", help="Show planned actions without writing files")
+    init_parser.add_argument(
+        "--no-agents",
+        action="store_true",
+        help="Skip generating .codex/ and .claude/ files",
+    )
+    init_parser.add_argument(
+        "--paper-template",
+        choices=["latex", "blank"],
+        help="Paper template style for paper/paper.typ (latex or blank)",
+    )
+
+    return parser
+
+
+def _prompt_paper_template() -> str:
+    print("Choose paper template for paper/paper.typ:")
+    print("1) latex (LaTeX-like layout) [recommended]")
+    print("2) blank (empty starter file)")
+    while True:
+        choice = input("Enter 1 or 2 [1]: ").strip()
+        if choice in ("", "1"):
+            return "latex"
+        if choice == "2":
+            return "blank"
+        print("Invalid choice. Please enter 1 or 2.")
+
+
+def _command_init(args: argparse.Namespace) -> int:
+    target_dir = Path(args.target_dir).expanduser().resolve()
+    project_name = args.project_name or target_dir.name
+    include_agents = not args.no_agents
+    paper_template = args.paper_template
+    if paper_template is None:
+        if sys.stdin.isatty():
+            paper_template = _prompt_paper_template()
+        else:
+            paper_template = "latex"
+
+    templates_dir = resources.files("blank_cli") / "templates"
+    templates_path = Path(str(templates_dir))
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        actions = plan_actions(
+            target_dir=target_dir,
+            templates_dir=templates_path,
+            project_name=project_name,
+            include_agents=include_agents,
+            paper_template=paper_template,
+            force=args.force,
+        )
+    except ScaffoldConflictError as exc:
+        print(str(exc), file=sys.stderr)
+        return 3
+
+    counts = apply_actions(
+        actions=actions,
+        target_dir=target_dir,
+        templates_dir=templates_path,
+        project_name=project_name,
+        include_agents=include_agents,
+        paper_template=paper_template,
+        dry_run=args.dry_run,
+    )
+
+    mode = "DRY RUN" if args.dry_run else "DONE"
+    print(f"[{mode}] blank init -> {target_dir}")
+    print(f"paper_template={paper_template}")
+    print(
+        f"created_dirs={counts['created_dirs']} created_files={counts['created_files']} "
+        f"replaced_files={counts['replaced_files']} skipped={counts['skipped']}"
+    )
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "init":
+        return _command_init(args)
+
+    parser.print_usage()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

blank_cli/scaffold.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Dict, List
+
+
+@dataclass(frozen=True)
+class ScaffoldAction:
+    action: str
+    path: Path
+
+
+class ScaffoldConflictError(RuntimeError):
+    pass
+
+
+DIRECTORIES: List[str] = [
+    "analysis/scripts",
+    "analysis/data/base",
+    "analysis/data/covariates",
+    "analysis/data/rworg",
+    "analysis/data/ocr_tables",
+    "analysis/output/figures",
+    "analysis/output/tables",
+    "analysis/output/results",
+    "paper",
+    "idea",
+]
+
+TEMPLATE_FILES: List[str] = [
+    "README.md.tpl",
+    ".gitignore.tpl",
+    ".here.tpl",
+    "analysis/scripts/00_setup.R.tpl",
+    "analysis/scripts/20_data.R.tpl",
+    "analysis/scripts/30_results_main.R.tpl",
+    "analysis/data/codebook.md.tpl",
+    "paper/ref.bib.tpl",
+    "paper/aesthetics.typ.tpl",
+    "analysis/output/figures/.gitkeep.tpl",
+    "analysis/output/tables/.gitkeep.tpl",
+    "analysis/output/results/.gitkeep.tpl",
+    ".codex/project.md.tpl",
+    ".codex/config.toml.tpl",
+    ".claude/settings.local.json.tpl",
+]
+
+PAPER_TEMPLATE_MAP = {
+    "latex": ("paper/paper_latex.typ.tpl", "paper/paper.typ"),
+    "blank": ("paper/paper_blank.typ.tpl", "paper/paper.typ"),
+}
+
+
+def _render_template(content: str, variables: Dict[str, str]) -> str:
+    rendered = content
+    for key, value in variables.items():
+        rendered = rendered.replace(f"{{{{{key}}}}}", value)
+    return rendered
+
+
+def _is_agent_file(template_path: str) -> bool:
+    return template_path.startswith(".codex/") or template_path.startswith(".claude/")
+
+
+def _output_path_from_template(template_path: str) -> Path:
+    if not template_path.endswith(".tpl"):
+        raise ValueError(f"Template path must end with .tpl: {template_path}")
+    return Path(template_path[:-4])
+
+
+def _effective_templates(paper_template: str) -> List[str]:
+    if paper_template not in PAPER_TEMPLATE_MAP:
+        raise ValueError(f"Unsupported paper template: {paper_template}")
+    _paper_src, paper_out = PAPER_TEMPLATE_MAP[paper_template]
+    return TEMPLATE_FILES + [f"{paper_out}.tpl"]
+
+
+def plan_actions(
+    target_dir: Path,
+    templates_dir: Path,
+    project_name: str,
+    include_agents: bool,
+    paper_template: str,
+    force: bool,
+) -> List[ScaffoldAction]:
+    variables = {
+        "project_name": project_name,
+        "today": str(date.today()),
+    }
+    actions: List[ScaffoldAction] = []
+
+    for rel_dir in DIRECTORIES:
+        out_dir = target_dir / rel_dir
+        if out_dir.exists():
+            actions.append(ScaffoldAction("skip_dir", out_dir))
+        else:
+            actions.append(ScaffoldAction("create_dir", out_dir))
+
+    effective_templates = _effective_templates(paper_template)
+    paper_src, paper_out = PAPER_TEMPLATE_MAP[paper_template]
+    virtual_paths = {f"{paper_out}.tpl": paper_src}
+
+    for template_rel in effective_templates:
+        source_template_rel = virtual_paths.get(template_rel, template_rel)
+        if not include_agents and _is_agent_file(template_rel):
+            continue
+
+        template_file = templates_dir / source_template_rel
+        if not template_file.exists():
+            raise FileNotFoundError(f"Missing template file: {template_file}")
+
+        out_file = target_dir / _output_path_from_template(template_rel)
+        rendered_content = _render_template(template_file.read_text(encoding="utf-8"), variables)
+
+        if out_file.exists():
+            existing_content = out_file.read_text(encoding="utf-8")
+            if existing_content == rendered_content:
+                actions.append(ScaffoldAction("skip_file", out_file))
+            elif force:
+                actions.append(ScaffoldAction("replace_file", out_file))
+            else:
+                raise ScaffoldConflictError(
+                    f"Refusing to overwrite existing file: {out_file}. Use --force to replace scaffold files."
+                )
+        else:
+            actions.append(ScaffoldAction("create_file", out_file))
+
+    return actions
+
+
+def apply_actions(
+    actions: List[ScaffoldAction],
+    target_dir: Path,
+    templates_dir: Path,
+    project_name: str,
+    include_agents: bool,
+    paper_template: str,
+    dry_run: bool,
+) -> Dict[str, int]:
+    variables = {
+        "project_name": project_name,
+        "today": str(date.today()),
+    }
+    counts = {
+        "created_dirs": 0,
+        "created_files": 0,
+        "replaced_files": 0,
+        "skipped": 0,
+    }
+
+    effective_templates = _effective_templates(paper_template)
+    paper_src, paper_out = PAPER_TEMPLATE_MAP[paper_template]
+    virtual_paths = {f"{paper_out}.tpl": paper_src}
+    template_index = {}
+    for template_rel in effective_templates:
+        source_template_rel = virtual_paths.get(template_rel, template_rel)
+        if include_agents or not _is_agent_file(template_rel):
+            template_index[_output_path_from_template(template_rel)] = templates_dir / source_template_rel
+
+    for item in actions:
+        if item.action == "create_dir":
+            counts["created_dirs"] += 1
+            if not dry_run:
+                item.path.mkdir(parents=True, exist_ok=True)
+            continue
+
+        if item.action == "skip_dir" or item.action == "skip_file":
+            counts["skipped"] += 1
+            continue
+
+        output_rel = item.path.relative_to(target_dir)
+        template_path = template_index.get(output_rel)
+        if template_path is None:
+            raise RuntimeError(f"No template found for output file {output_rel}")
+
+        content = _render_template(template_path.read_text(encoding="utf-8"), variables)
+
+        if item.action == "create_file":
+            counts["created_files"] += 1
+        elif item.action == "replace_file":
+            counts["replaced_files"] += 1
+        else:
+            raise RuntimeError(f"Unsupported action: {item.action}")
+
+        if not dry_run:
+            item.path.parent.mkdir(parents=True, exist_ok=True)
+            item.path.write_text(content, encoding="utf-8")
+
+    return counts

blank_cli/templates/.claude/settings.local.json.tpl

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "allow": []
+  }
+}

blank_cli/templates/.codex/config.toml.tpl

@@ -0,0 +1,8 @@
+[mcp_servers.zotero]
+command = "zotero-mcp"
+args = []
+env = { ZOTERO_LOCAL = "true" }
+
+[mcp_servers.markitdown]
+command = "uvx"
+args = ["markitdown-mcp"]

blank_cli/templates/.codex/project.md.tpl

@@ -0,0 +1,19 @@
+# Project: {{project_name}}
+
+## Overview
+
+Research workspace scaffolded by `blank` on {{today}}.
+
+## Agent Rules
+
+- Ask before destructive file operations.
+- Keep `analysis/data/codebook.md` synchronized with data changes.
+- Regenerate outputs when analysis scripts change.
+
+## Directory Structure
+
+- `analysis/scripts/`
+- `analysis/data/`
+- `analysis/output/`
+- `paper/`
+- `idea/`

blank_cli/templates/.gitignore.tpl

@@ -0,0 +1,11 @@
+.DS_Store
+.venv/
+.tmp/
+__pycache__/
+*.pyc
+analysis/output/figures/*
+analysis/output/tables/*
+analysis/output/results/*
+!analysis/output/figures/.gitkeep
+!analysis/output/tables/.gitkeep
+!analysis/output/results/.gitkeep

blank_cli/templates/README.md.tpl

@@ -0,0 +1,20 @@
+# {{project_name}}
+
+Research project scaffold initialized by `blank` on {{today}}.
+
+## Structure
+
+- `analysis/`: data pipelines, scripts, generated outputs
+- `paper/`: manuscript files
+- `idea/`: brainstorming notes
+- `.codex/`: agent workflow config
+
+## Quickstart
+
+```bash
+# initialize from repo root
+blank init .
+
+# run the analysis skeleton
+Rscript analysis/scripts/30_results_main.R
+```

blank_cli/templates/analysis/data/codebook.md.tpl

@@ -0,0 +1,9 @@
+# Codebook: {{project_name}}
+
+Last scaffold update: {{today}}
+
+## Variables
+
+| variable | type | source | description |
+|---|---|---|---|
+| example_var | numeric | placeholder | Replace with actual variable docs |

blank_cli/templates/analysis/scripts/00_setup.R.tpl

@@ -0,0 +1,9 @@
+# 00_setup.R
+# Shared setup for analysis scripts.
+
+message("[setup] loading configuration")
+
+cfg <- list(
+  project_name = "{{project_name}}",
+  generated_on = "{{today}}"
+)

blank_cli/templates/analysis/scripts/20_data.R.tpl

@@ -0,0 +1,6 @@
+# 20_data.R
+# Data preparation entrypoint.
+
+source("analysis/scripts/00_setup.R")
+
+message("[data] build data objects here")

blank_cli/templates/analysis/scripts/30_results_main.R.tpl

@@ -0,0 +1,7 @@
+# 30_results_main.R
+# Main analysis entrypoint.
+
+source("analysis/scripts/00_setup.R")
+source("analysis/scripts/20_data.R")
+
+message("[results] write analysis outputs into analysis/output/")

blank_cli/templates/paper/aesthetics.typ.tpl

@@ -0,0 +1 @@
+// Placeholder style helpers for Typst manuscript customization.

blank_cli/templates/paper/paper_blank.typ.tpl

@@ -0,0 +1 @@
+# {{project_name}}

blank_cli/templates/paper/paper_latex.typ.tpl

@@ -0,0 +1,12 @@
+#set page(margin: (x: 1in, y: 1in), numbering: "1")
+#set text(font: "Libertinus Serif", size: 11pt)
+#set par(justify: true, leading: 0.7em)
+#set heading(numbering: "1.")
+
+#heading(level: 1)[{{project_name}}]
+
+#outline(title: [Contents])
+
+#heading(level: 1)[Introduction]
+
+Write your manuscript here.

blank_cli/templates/paper/ref.bib.tpl

@@ -0,0 +1,6 @@
+@article{example2026,
+  title={Example Reference},
+  author={Doe, Jane},
+  journal={Journal of Placeholder Studies},
+  year={2026}
+}