lov-cli-creator v0.1.1A

Immutable. This exact content never changes and is served at /api/v1/blob/1a1c5be0cc48ef35.

---
name: lov-cli-creator
description: >
  把本地项目或当前目录转换为可安装、可测试、支持 JSON 的真实后端 CLI；当用户说“给这个项目做 CLI”“把应用变成命令行”或 “build a CLI for this project” 时使用。
license: MIT
metadata:
  author: contributors
  version: "0.1.1"
  card_standard: lovstudio/skill-card/v1
  tags:
    - cli
    - agent-harness
    - codebase-analysis
    - automation
    - developer-tools
  compatibility: "Python 3.9+; generated CLIs use only the Python standard library unless the target backend requires more."
  dependencies: []
---

# CLI 工坊 · CLI Studio

Turn a real local project into an installable command-line interface that both
people and agents can operate. The generated CLI exposes the project's actual
backend, emits stable JSON, documents its contract, and carries executable tests.

## Triggers

### Activate when

- “给这个项目做一个 CLI”“把当前应用变成命令行”“为这个仓库生成 Agent CLI”。
- “从这个项目路径输出一个可安装的命令行工具”。
- “Build a CLI for this project” or “make this application agent-accessible”.
- The user wants to refine or validate a CLI previously generated by this Skill.

### Do not activate when

- The user only wants a new Web/Tauri application; use an app-generation workflow.
- The user only needs one shell alias or a single ad-hoc command, not a maintained CLI.
- The user asks to publish a package or release; this Skill stops at a locally
  installed and verified CLI.
- The target is a closed binary with no callable API, scripting surface, protocol,
  or native file format. Diagnose the missing backend boundary before generating.

## User Profile (cross-session)

Read `skill.yaml` on every invocation. Resolve values in this order: the current
request, project context, `skills.lov-cli-creator.records`, shared preferences,
the shared user/workspace Profile, then safe defaults. Project path defaults to
the directory in which the Skill is invoked; output defaults to
`agent-harness/` inside that project.

Persist only a directly stated durable preference, such as a user's long-term
command prefix or output-directory convention:

```bash
python3 "$SKILL_DIR/scripts/profile_store.py" record \
  --skill-id lov-cli-creator \
  --path records.command_prefix \
  --value '"lov-cli"' \
  --confirm
```

Report the saved Profile path. Never persist inferred paths, credentials, or
tokens. See [the Profile contract](references/user-profile.md).

## Skill Group Composition

Read [the composition record](references/skill-composition.md) before invoking
an adjacent Skill. `lov-cli-creator` owns the finished CLI; other Skills are
optional artifact-level handoffs and never hidden runtime dependencies.

## Workflow (MANDATORY)

Follow these steps in order. Do not report a scaffold as a completed CLI.

### Step 0: Resolve the Skill and target project

1. Resolve `SKILL_DIR` from the active Skill context.
2. Resolve the target from the user's path; if omitted, use the Skill invocation
   working directory, not the installed Skill directory.
3. Resolve symlinks, confirm the directory exists, and read applicable
   `AGENTS.md`, `CLAUDE.md`, repository instructions, and dirty-worktree state.
4. Preserve unrelated files and changes. Never overwrite an occupied output
   directory with the scaffold helper.

Manual helper invocation:

```bash
python3 "$SKILL_DIR/scripts/inspect_project.py" . --format markdown
```

### Step 1: Analyze the real callable surface

Run the inspector and then verify its signals against source code:

```bash
python3 "$SKILL_DIR/scripts/inspect_project.py" PROJECT \
  --format json --output PROJECT_ANALYSIS.json
```

Identify the product domains, existing commands, public APIs, native data model,
state lifecycle, export/render path, and external runtime dependencies. Map user
actions to real callable functions or executables. Prefer, in order:

1. an existing project CLI or scripting API;
2. the project's public library/service API;
3. direct manipulation of its documented native format followed by its real
   renderer or runtime;
4. a narrow subprocess or protocol adapter.

Do not rebuild the product in the harness. For GUI/media applications, rendering
must use the real engine. For services, use the real local service/API boundary.
For libraries, call the public API rather than copying implementation logic.
Read [project analysis rules](references/project-analysis.md).

### Step 2: Design the CLI contract before generating files

Define command groups around user tasks, not source filenames. Every CLI must
include `doctor`, `info`, and `capabilities`, plus at least one project-specific
command. Every command must work in human-readable mode and with global `--json`.

Write a `lov-cli-plan/v1` JSON plan. For existing executables, declare fixed
argv prefixes and typed parameters so the generated bridge can be complete
without shell evaluation. For an in-process library or protocol, use the plan to
scaffold the command contract, then implement the adapter in generated source.

Read [the plan schema](references/cli-plan.md) and
[the CLI contract](references/cli-contract.md). Include:

- command name, description, inputs, output, mutability, and exit behavior;
- state persistence, concurrency, undo/redo, and idempotency rules when relevant;
- real backend dependency and install diagnostics;
- output verification for every export or mutation with a material artifact.

### Step 3: Scaffold the harness

Generate into `PROJECT/agent-harness` unless the request or Profile supplies a
different output directory:

```bash
python3 "$SKILL_DIR/scripts/scaffold_cli.py" PROJECT \
  --plan CLI_PLAN.json
```

The helper creates a Python package, console entry point, JSON contract, backend
bridge, README, test plan, and tests. It rejects occupied output paths. Use
`--output` only when a separate location is required. The default console command
is `lov-cli-PROJECT_SLUG`, unless the plan declares another safe kebab-case name.

If an existing generated harness is present, inspect and refine it in place.
Never discard working commands merely to rerun the scaffold.

### Step 4: Complete the real backend adapter

The generated subprocess bridge is production-usable when the plan fully maps an
existing executable. Otherwise implement the missing adapter in
`src/PACKAGE/backend.py` and register its typed command handler in `cli.py`.

Requirements:

- use argument arrays with `shell=False`; never concatenate untrusted shell text;
- resolve executables explicitly and return actionable dependency errors;
- make read-before-write introspection cheap;
- return stable JSON envelopes and nonzero exit codes on failure;
- verify postconditions instead of trusting exit status alone;
- auto-save one-shot state mutations unless `--dry-run` is set;
- lock persistent session files when concurrent writes are possible;
- keep secrets out of argv echoes, logs, JSON, and generated source.

For stateful tools, support both one-shot commands and a REPL only when a REPL
adds genuine value. Do not force statefulness onto a stateless project.

### Step 5: Test the installed command through real workflows

Complete `TEST.md` as a plan before adding test code. Keep fast unit tests and
real end-to-end tests. The E2E suite must invoke the installed console command
from outside the harness directory, exercise at least one project-specific
workflow, and verify resulting state or artifacts programmatically.

Install into an isolated environment or the project-approved environment:

```bash
python3 -m pip install -e PROJECT/agent-harness
python3 -m unittest discover -s PROJECT/agent-harness/tests -v
```

When a Python 3.9 venv bundles pip older than 21.3, install the generated
`requirements.txt` and run `python3 setup.py develop` from the harness as the
local editable-install fallback. Do not require a network-only pip upgrade.

If the backend dependency is unavailable, the real-backend E2E test fails with
installation guidance; it must not silently skip or replace the backend. Read
[the testing requirements](references/testing.md).

### Step 6: Mark ready and validate

Set `status` in `lov-cli.json` to `ready` only after the domain commands and E2E
tests pass. Then run:

```bash
python3 "$SKILL_DIR/scripts/validate_cli.py" PROJECT/agent-harness \
  --run-tests --require-installed
```

Validation must confirm the package entry point, source/module invocation, JSON
envelopes, built-in introspection, at least one domain command, unit/E2E tests,
and the installed command from a neutral working directory.

### Step 7: Report the finished artifact

Report the target project, harness path, installed command, command groups,
backend used, tests and validation results, and any verified limitation. Clearly
separate local readiness from package publication; publication is outside scope.

## Dependencies

- Python 3.9+ to run the helpers and generated standard-library CLI.
- The target project's real runtime or executable for backend validation.
- PyYAML only for validating this Skill source with `scripts/validate_skill.py`.

## Provenance

This workflow adapts the CLI-Anything agent-harness methodology while broadening
it from GUI applications to local projects and replacing legacy packaging rules
with a small PEP 621 harness. See [upstream research](references/upstream-research.md)
for the source, license, and deliberate differences.

## Runtime context (shared)

运行前读取本 Skill 包的 `skill.yaml`。只使用 Manifest 声明的字段；Profile
保存用户和工作区长期偏好，`skills.lov-cli-creator.records` 保存本 Skill 的持久
记录。报错提供可复制的 `context_id`、字段路径与来源，诊断不得泄露秘密。